Nesting to Navigate

Last updated
Save as PDF

To retrieve the data you need in a document template, you must utilize the built-in relationships among the objects in the Object Model. These relationships are reflected in the tags you write in the document template as either nested tags or paths written within a tag attribute.

Nesting tags in a document template is equivalent to navigating throughout the Object Model to build paths to the data you want to retrieve. Each time you nest a tag, you are "traversing" between two objects in the Object Model using a relationship that exists between them. When you open a tag but do not close it, you point the Document Generator to the object to which that particular item has a relationship. The next tag you use refers to that object. When you are finished using data and relationships from that object, close the nested tag to return to the object that you started from.

Nesting to navigate can start with any piece of data that identifies another object. System fields, custom fields, related objects, and sub-objects can all have relationships to other objects. Therefore, you can even nest a tag after pointing to a system field or a custom field.

In order to find out whether a field points to another object, or how two objects are related, see Object Model: Read This First. Information here indicates whether an object attribute points to another object by indicating the data type Object in the Data Type column of each table.

For example, suppose you have two custom objects named Claim and Policy, where:

Claim is a child of Policy.
Policy is contact-centric.
Claim has a custom field of type Custom Object that is used for selecting another claim as the Master Claim.

If the following tags were in a document template for the Claim object, they would retrieve data from the policy that is the parent of the master claim:

<tc:detail select="CLAM/MasterClaims"> <tc:data select="Parent"> <tc:data select="Contact"> <tc:data select="FirstName" /> <tc:data select="Name" /> <tc:loop select="AddressList" qualifier="Type_TreePosition=ADDR_BUS1"> <tc:data select="Street" /> <tc:data select="City" /> <tc:data select="State" /> <tc:data select="PostalCode" /> </tc:loop> <tc:data select="SsOrTaxNumberString" /> <tc:data select="DriverLicense" /> </tc:data> </tc:data> </tc:detail>

The following table provides a detailed explanation of each line of code in this example.

Line #	Example	Description
1	`<tc:detail select="CLAM/ MasterClaims">`	This tc:detail tag points to the custom field MasterClaims in the current claim. Since the tag is not closed, the Document Generator navigates to the Claim record selected in this custom field, known as the master claim. Also, since the tag is not closed, nothing is printed in the generated document.
2	`<tc:data select="Parent">`	This tc:data tag points to the system field where the parent record is selected. Since the tag is not closed, the Document Generator navigates to the parent record, which is a policy. Also, since the tag is not closed, nothing is printed in the generated document.
3	`<tc:data select="Contact">`	This tc:data tag points to the system field where a contact is selected for a contact- centric record. Since the tag is not closed, the Document Generator navigates to the Contact record. Also, since the tag is not closed, nothing is printed in the generated document.
4	`<tc:data select="FirstName" />`	This tc:data tag points to the system field where the contact's first name is stored. The tag is closed, so the Document Generator does not navigate but remains in the Contact object. Also, since the tag is closed, the value of the field is printed in the generated document.
5	`<tc:data select="Name" />`	This tc:data tag points to the system field where the contact's last name is stored. The tag is closed, so the Document Generator does not navigate but remains in the Contact object. Also, since the tag is closed, the value of the field is printed in the generated document.
6	`<tc:loop select="AddressList" qualifier="Type_TreePosition=ADDR_BUS1">`	This tc:loop tag points to the Address sub- object of the Contact object. The qualifier attribute limits the sub- object to addresses of type BUS1 only. Since the tag is not closed, the Document Generator navigates to the list of addresses added to the contact record. Also, since the tag is not closed, nothing is printed in the generated document.
7	`<tc:data select="Street" /> <tc:data select="City" /> <tc:data select="State" /><tc:data select="PostalCode" />`	These tc:data tags point to the system field where the street, city, state and postal code are stored for the address. Each tag is closed, so the Document Generator does not navigate but remains in the Address sub-object. Also, since each tag is closed, the value of the field is printed in the generated document.
8	`</tc:loop>`	This is the closing tag for tc:loop. When this tc:loop is closed, the Document Generator navigates back from the Address sub-object to the Contact object.
9	`<tc:data select="SsOrTaxNumberString" />` `<tc:data select="DriverLicense" / >`	These tc:data tags point to the system fields where the contact's social security number and driver license number are stored. Each tag is closed, so the Document Generator does not navigate but remains in the Contact object. Also, since each tag is closed, the value of the field is printed in the generated document.
10	`</tc:data>`	This is the closing tag for the tc:data tag that we left open on line 3. When this tc:data tag is closed, the Document Generator navigates back from the Contact to the Policy object.
11	`</tc:data>`	This is the closing tag for the tc:data tag that we left open on line 2. When this tc:data tag is closed, the Document Generator navigates back from the Policy object to the Claim object.
12	`</tc:detail>`	This is the closing tag for the tc:detail tag that we left open on line 1. When this tc:detail tag is closed, the Document Generator navigates back from the Master Claim selected in the custom field to the starting Claim.