Understanding Newforma Field Tags

7 minutes
11 months ago

Understanding Newforma Field Tags

When creating Microsoft Word form templates, a Newforma field tag with XML node, element, or attribute names in a template will pull specific data from an XML data file during a merge. To better understand the relationship of roots, children, attributes, and elements, see the following illustrations. The example on the left illustrates the various relationships and naming conventions in an XML file. The image on the right represents one book in the XML on the left.

The root element in the example above is <bookstore>. All <book> elements in the document are contained within <bookstore>.

The <book> element has four children: <title>,< author>, <year>, and <price>. The <title> element has one attribute (lang) and one value. The <year> element is considered a leaf node because it has no children or attributes.

Definitions

Non-leaf node is an element that has child elements or attributes.

Leaf node or leaf element is an element without any child nodes.

For the Newforma mail merge functionality, the following tag options are available and their usage is described below.

The maximum displayed text of a merge field in Word is 45 characters, so the full field tag may not be displayed. Editing the field will show the entire field text.

 NFField:NodeName:ElementorAttributeName takes the value of the element or attribute of a specific node. In the following example , <Project> is the NodeName. It is the parent element or node. <Name> is the child of <Project> and is a leaf element.

                «NFField:Project:Name»

                XML File Node and Element:

                <Project>

                                <Name>Project 2</Name>

                </Project>

NFSectionStart:NodeName marks the beginning of a section using values from non-leaf nodes of an XML file. If you have multiple fields from the same node, you could use this tag to group those elements. Elements with an NFSectionStart/NFSectionEnd pair will be repeated if the XML file has multiple instances of the element. The NFSectionStart:NodeName tag  must be closed with a matching NFSectionEnd:NodeName field tag.

<ContentDescription quantity=”1″ dated=”3/20/2011″ description=”42.xls” number=”” action=”” remarks=”” scale=”” size=”” revision=”” />

NFSectionEnd:NodeName marks the end of a section using values from non-leaf nodes of an XML file. The section must be started with a matching NFSectionEnd:NodeName field tag.

 

NFOptionalStart:NodeName marks the beginning of an optional  section using values from non-leaf nodes of an XML file. Use this field tag in combination with the NFOptionalEnd:NodeName tag to display data that is optional. If there are no values for the node in the XML file, all content between the NFOptional Start and NFOptionalEnd  field tags will not be rendered. If there is data, the data will be displayed in the same way as for an NFSectionStart/NFSectionEnd pair. The NFOptionalStart:NodeName  must be closed with a matching NFOptionalEnd:NodeName field tag. In the example below, if there were no <ContentDescriptions>  nodes in the xml data file, the “Description of Contents” header and the entire table would be removed from the rendered document.

                <ContentDescriptions>

                                <ContentDescription quantity=”1″ dated=”3/20/2011″ description=”42.xls” number=”” action=”” remarks=”” scale=”” size=”” revision=”” />

                </ContentDescriptions>

                              «NFOptionalStart:ContentDescriptions»

                             

«NFOptionalEnd:ContentDescriptions»

 

NFOptionalEnd:NodeName marks the beginning of a section using values from non-leaf nodes of an XML file that is optional. If there are no values for the node in the XML file, all content between the NFOptional Start and NFOptionalEnd  field tags will not be rendered. The section must be closed with a matching NFSectionEnd:NodeName field tag.

 

NFField:NodeName:Image:ElementorAttributeName takes the value of the element or attribute of a node (which should be a URL or filepath) and renders an image.

                «NFField:TransmittalNotificationData:Imag»   (NFField:TransmittalNotificationData:Image:TemplateLogowhen viewed in the merge field editor)

                <TransmittalNotificationData>

                                <TemplateLogo>http://www.newforma.com/images/jeffersonmilllogo.png</TemplateLogo>

                                <NPCSCompanyName>Jefferson Mill Associates</NPCSCompanyName>

                                <NPCSCompanyAddress>55 Mill Way | Manchester, NH 03103</NPCSCompanyAddress>

                <TransmittalNotificationData>

 

«NFField:NodeName:Hyperlink:label:url» takes the values of the elements or attributes of a node (which should represent a hyperlink and associated label) and renders a hyperlink.

          «NFField:Link:Hyperlink:label:url»

          <Link label=”Link to website” url=”http://www.website.com” />

 

«NFField:Nodename:checkbox:ElementOrAttributeName:Value» inserts a checkbox. The checkbox will be checked/unchecked based on the value of the element or attribute. In the example below, a checkbox will be inserted. It will be checked if the value of the Purpose element in the Transmittal node is “For your approval.” Otherwise the checkbox will be unchecked. (Note the use of underscores to represent spaces.)

NFField:Transmittal:checkbox:Purpose:For_ your_ approval

«NFOptSecByValStart:NodeName:ElementOrAttribute:value» makes a section optional based on the value of an element or attribute. In the example below, any content between the NFOptSecByValStart/End tags will not be displayed if the value of the “HasMinutes” attribute in the “Meeting” node is equal to “Yes.” To test for an empty value, us NF_EMPTY.

For values with spaces, use an underscore (_) to denote a space.

       «NFOptSecByValStart:Meeting:HasMinutes:Ye»

      <Meeting>

            <Subject>Meeting Test 2</Subject>

            <Location></Location>

            <Date>12/5/2011 at 8:00 AM to 8:30 AM</Date>

            <Type>Client Meeting</Type>

            <HasAgenda>Yes</HasAgenda>

            <HasMinutes>Yes</HasMinutes>

            <AllDayEvent>No</AllDayEvent>

              .

              .

     <Meeting>

 

«NFOptSecByValEnd:NodeName:ElementOrAttribute:value» makes a section optional based on the value of an element or attribute.

« NFOptSecLTStart:NodeName:ElementOrAttribute:number» makes a section optional based on whether a number is less than a certain value. In the example below, any content between the NFOptSecByLTStart/End tags will not be displayed if the value of the “filecount” attribute in the “files” node is less than 501.  For example:

     « NFOptSecLTStart:Files:filecount:501»     

     <Files filecount=”425″/>

           

 «NFOptSecLTEnd:NodeName:ElementOrAttribute:value» makes a section optional based on whether a number is less than a certain value.

 « NFOptSecGTStart:NodeName:ElementOrAttribute:number» makes a section optional based on whether a number is greater than a certain value. In the example below, any content between the NFOptSecByGTStart/End tags will not be displayed if the value of the “filecount” attribute in the “files” node is greater than 500. For example:

     « NFOptSecGTStart:Files:filecount:500»     

     <Files filecount=”425″/>

           

 «NFOptSecGTEnd:NodeName:ElementOrAttribute:value» makes a section optional based on whether a number is greater than a certain value.

Word’s IF construct: Word has an IF field that you can use to display content conditionally. In the example below, if the “street” attribute of the sender node is not empty, a comma is output between the street and city, otherwise an empty string (nothing) is output. For more information, see Microsoft’s Examples of IF fields.

 

NFSectionStart/End, NFOptionalStart/End, and NFField tags for the same node should not be duplicated in a paragraph or table row, or an error will result when the mail merge is processed. For example, the following would result in an error:
This document was generated by «NFField:Newforma:application» ««NFField:Newforma:version»

The correct way to generate the desired result would be:
«NFSectionStart:Newforma»This document was generated by «application» «version»«NFSectionEnd:Newforma»

Word will only display the first 45 characters of a merge field name. To view the entire field, you must use the Edit Merge Field dialog box.

Example

The following example shows a template with various Newforma mail merge fields, the XML file used, and the rendered document. The document on the left is the template created with Newforma field tags. The document on the right is the resulting document once it has been processed. (This example was generated for an outgoing transmittal.)

The following example is the raw data used during the mail merge. Typically you would never see or modify this file.