Defining Filter Pages

tc:filter Tag Attributes

The tag attributes noted in the following table are the basic tags you need to create any type of filter page.
In addition to these tag attributes, all tc:filter tags in your header must use at least one other tag attribute to identify an object or sub-object.

tc:filter Tag Attributes

Required ?	Tag attribute	Possible attribute value	Description
Yes	`name`	"FilterName"	Specify a name that uniquely identifies the filter. A name that indicates which object the filter points to is helpful. Important: This attribute value must exactly match the select="" attribute value of the corresponding tc:filter tag you entered in the content section. You can either define the filter first or write the content section first and define the filter later, but you must use the same name of the filter in both places. Using spaces in the name of the filter is not recommended.
No	`hidden`	"yes" or "no"	Indicate whether the filter should be displayed to the user as a filter page, or applied automatically in the background. By default, hidden="no". When hidden="yes", you must provide the attribute list="yes" in the content section of the template where this filter is referenced. For details, see tc:filter.
Yes	`label`	"UserInstructions"	Enter a label that appears as instructions for the user within the filter page.
Yes	`displayString`	"Data;Data;Data"	Specify how the selections appears for the user within the filter page. Multiple data items must be separated by semicolons (;). For example, displayString="Contact/ FirstName;Contact/Name;DefaultCategory/Name" Note: You can only include system fields in the displayString. Custom fields cannot be included.
Yes	`displayForm at`	"* * - *"	Specify the format of the information displayed by the displayString by typing an asterisk () for each data item, and typing any other desired characters, such as hyphens and spaces. Each data item retrieved by the displayString attribute must be represented by an asterisk () in the displayFormat attribute.
No	`multi`	"yes" or "no"	Type multi="yes" to allow users to select multiple items simultaneously from within the filter page. By default, only one item may be selected. You do not have to type multi="no" to allow only one selection in the filter page. Caution: Do not use multi="yes" when referencing the filter as a main filter. For details, see Main Filters and Sub-Filters.
Each attribute with an astrisk (*) is required	*searchCondition	searchCondition identifies a related object. For details, see Filters for Related Objects.
Each attribute with an asterisk (*) is required	`qualifier` (used with searchCondition)	searchCondition identifies a related object. For details, see Filters for Related Objects.
Each attribute with an asterisk (*) is required	*test	test identifies a sub-object or a single object record selected in a system field. For details, see Filters for Sub-objects and Single Records.
Ea ch attribute with anasterisk (*) is required	*entity	entity identifies an object that is not related to the main object. For details, see Filters for Non-Related Objects.
Ea ch attribute with an a st e r i sk (*) is required	`criteria` (used with entity)	entity identifies an object that is not related to the main object. For details, see Filters for Non-Related Objects.

Filters for Related Objects

When you want a filter page to identify an object that is directly related to either the main object or to an object identified by another filter, use the searchCondition tag attribute of tc:filter. This tag attribute is used to provide the user with a list of related objects.

The tag attributes for identifying related objects are described in the following table. Use these tag attributes in combination with the basic tag attributes in The tc:filter Tag Attributes table.

searchCondition Tag Attribute of tc:filter

Tag attribute	Possible attribute value	Description
`searchCondition`	"RelatedObject"	Type the name of the related object for which you want to define a filter. Type name of the object as follows: `Appointment Account Expense History Involved Task` Project (for child custom objects and embedded objects only) Note: You must include the qualifier attribute, if you are defining a filter page to retrieve child objects.
`qualifier`	"Application_ProjObjectDefinition_UniqueCode=UCOD"	This tag attribute is required when you are defining a filter page for a child custom object, child account, or an embedded object. This attribute value identifies the child object using the following values: Path of the object attribute that uniquely identifies the child or embedded object, which is Application_ProjObjectDefinition_UniqueCode. Unique code of the child or embedded object, which can be copied from the Object Definition List in the user interface.

Tag attribute

Possible attribute value

Description

searchCondition

"RelatedObject"

Type the name of the related object for which you want to define a filter. Type name of the object as follows:

Appointment Account Expense History Involved Task

Project (for child custom objects and embedded objects only)

Note: You must include the qualifier attribute, if you are defining a filter page to retrieve child objects.

qualifier

"Application_ProjObjectDefinition_UniqueCode=UCOD"

This tag attribute is required when you are defining a filter page for a child custom object, child account, or an embedded object.

This attribute value identifies the child object using the following values:

Path of the object attribute that uniquely identifies the child or embedded object, which is Application_ProjObjectDefinition_UniqueCode.
Unique code of the child or embedded object, which can be copied from the Object Definition List in the user interface.

Let's see how the tc:filter tag and its attributes were used in the content and header sections in order to create the filter page shown in the tc:filter Tag Attributes table. In this example, the tc:filter tag is defining a filter page where the user selects a record belonging to the Involved object, which is a related object of the main object Claim.

Notice how the select attribute value in the content section below exactly matches the name attribute value in the header section.

Header

<tc:filter name="InvolvedParty" searchCondition="Involved" hidden="no" label="Please select Claimant" displayString="Contact/ FirstName;Contact/Name;DefaultCategory/Name" displayFormat="* * - *" />

Content

<tc:filter select="InvolvedParty"> <tc:data select="Contact/FirstName" /> <tc:data select="Contact/Name" /> </tc:filter>

You may need to create a filter page where the user selects a child custom object of the main object. In the following example, the filter allows the user to select a child Claim record belonging to a Policy record (the main object). In the header, the qualifier tag attribute of tc:filter specifies which child object of the Policy object that the filter page must display.

Header

<tc:filter name="SelectedClaim" searchCondition="Project" qualifier="Application_ProjObjectDefinition_UniqueCode=CLAM" label="Select the appropriate claim" displayString="Name;NumberString" displayFormat="* - *" />

Content

<tc:filter select="SelectedClaim"> <tc:data select="NumberString" /> <tc:data select="Name" /> </tc:filter>

For more examples of how searchCondition can be used, see Main Filters and Sub-Filters. Also, see Document Template Samples.

Filters for Sub-objects and Single Records

You may want users to select one or more sub-objects from which to retrieve data in a document. For example, you may want the user to select one address from the list of addresses belonging to a contact. In order to provide a filter page where the user selects a sub-object, use the test attribute in the tc:filter tag.

The test attribute can also identify a single record that is selected in a system field. Although you normally do not need a filter page that only gives the user one item to select, this becomes necessary when using tc:filter tags to navigate to the list of related records or sub-objects you want to provide to the user. For example, you may need a filter page where the user selects an Involved (related object) of the parent custom object record Policy (a single record). You will learn more about this in Main Filters and Sub-Filters.

The test tag attribute accepts a path as its value. The path must meet the following requirements:

It must be constructed of TeamConnect object attributes, according to the relationships between object attributes found in the Object Model.
It must end with an object attribute that identifies either a single record selected in a system field of a record, or a sub-object list.

The following table describes how to use the test tag attribute for tc:filter. Use this tag attribute in addition to the basic tag attributes noted in the tc:filter Tag Attributes table.

test Tag Attribute of tc:filter

Tag attribute	Possible attribute value	Description
test	"AttributePath" (attributes separated by underscores _ )	Use test to specify the path of object attributes separated by underscores (_) that identifies the object attribute that you want the user to select in the filter page. The object attribute identified by the path may be one of the following types: A sub-object from a sub-object list. Tips: Sub-object attributes contain the word "List" in the name of the object attribute (such as AssigneeList, AddressList, or LineItemList). Object Model: Read This First (and the additional reference tables it points to) describes all of the sub-objects for each main TeamConnect object. An object attribute that identifies a single record (such as the Parent or Contact for a custom object record). Displaying a single record in a filter page is useful when you need to navigate to a list you want the user to view. For more details about this scenario, see Single-Option Filters. Tip: An object attribute that identifies a single record has the data type "object" in this document.

Tag attribute

Possible attribute value

Description

test

"AttributePath"

(attributes separated by underscores _ )

Use test to specify the path of object attributes separated by underscores (_) that identifies the object attribute that you want the user to select in the filter page. The object attribute identified by the path may be one of the following types:

A sub-object from a sub-object list.

Tips:
- Sub-object attributes contain the word "List" in the name of the object attribute (such as AssigneeList, AddressList, or LineItemList).
- Object Model: Read This First (and the additional reference tables it points to) describes all of the sub-objects for each main TeamConnect object.
An object attribute that identifies a single record (such as the Parent or Contact for a custom object record).

Displaying a single record in a filter page is useful when you need to navigate to a list you want the user to view. For more details about this scenario, see Single-Option Filters.

Tip: An object attribute that identifies a single record has the data type "object" in this document.

Sample Values for Test Attribute

If you are identifying a sub-object list with the test attribute, the attribute and value might look like any of the following examples:

test="AssigneeList" (in a custom object)
test="AddressList" (in a contact)
test="Contact_AddressList" (in a contact-centric custom object)
test="Project_Contact_PhoneList" (in an expense record, to its project's contact-centric field's phone numbers)
test="Parent_AssigneeList" (in a child custom object, to its parent's assignees)

If you are identifying a single record that is selected in a system field with the test attribute, the attribute and value could look like any of the following examples:

test="Parent" (in a child custom object)
test="Parent_Contact" (in a child custom object, to its contact-centric parent)
test="Contact" (in a custom object, to the contact in its contact-centric field)
test="Project" (in an expense record)

Header

<tc:filter name="UserSelectedAssignee" test="AssigneeList" displayString="User/Contact/FirstName;User/Contact/Name;Type/Name" displayFormat="* * - *" label="Please select an assignee." />

Content

<tc:filter select="UserSelectedAssignee"> <tc:data select="User/Contact/FirstName" /> <tc:data select="User/Contact/Name" /> </tc:filter>

In the TeamConnect, the filter defined in the header tests the AssigneeList sub-object of the main object and displays a list of assignees in the filter page. In the content section, the first and last name of the assignee is generated in the document.

Header

<tc:filter name="SelectedAddress" test="Contact_AddressList" label="Please select the address of the Insured to which this letter should be mailed." displayString="Street;City;State;PostalCode" displayFormat="* *, * *" />

Content

<tc:filter select="SelectedAddress"> <tc:data select="Street" /> <tc:data select="City" />, <tc:data select="State"/> <tc:data select="PostalCode" /> </tc:filter>

In the TeamConnect, the test attribute of tc:filter in the header identifies the list of addresses for the contact selected in the contact-centric field (Insured) of the main object record. In the content section, the address selected by the user appears in the generated document.

Header

<tc:filter name="ParentPolicy" test="Parent" label="Please select the parent Policy below and click Next." displayString="Name" displayFormat="*" usedBy="1" />

In this example of a header only, the filter identifies the Policy selected as the parent in the main object record (the child Claim). This filter will be useful for then allowing the user to select the Policy's Involved parties in a subsequent filter. You will see how this is done in Single-Option Filters.

Filters for Non-Related Objects

When you want the user to select a record that is unrelated to the main object record, use tc:filter in the header section to define a filter page where the user will make this selection. To create the filter page for an unrelated object, use the tag attributes described in the tc:filter Tag Attributes table as well as those described in the following table.

Filter Tag Attributes - Creating Filter Pages for Non-Related Objects

Tag attribute	Possible attribute value	Description
`entity`	"EntityName"	Type the name of the object from which you want the user to select a record. The user will be able to select from all available records, regardless of whether or not they are related to the main object record. For example, using entity="Account" allows the user to select any available Account. If the entity is a custom object, you must type entity="Project" and use the criteria tag attribute to identify the unique code of the custom object. For example: criteria="objectDefinition='SDTX'".
`criteria`	Use any of the following components in the criteria attribute value: category='DefaultCategoryName' (the name of the default category of the records you want available in the filter page) objectDefinition='ProjectUniqueCode' (if the non-related object is a project, use this component to provide the unique code of the project whose records you want available in the filter page) name='RecordName' (the name of the record you want available in the filter page) numberstring='RecordNumber' (t he number of the record you want available in the filter page)	When using the entity tag attribute, you can specify criteria for which object records will be available to the user to select using the criteria tag attribute. This prevents all records in the system from being made available in the drop-down list in the filter page. You can use any combination of the four components. For each component, you include the value that is desired in order for that record to be available to the user in the filter page. When using the criteria tag components, you must use the following conventions: Component values are enclosed by single quotes. Type a comma between components when using more than one. Do not type any spaces between items or between commas in this tag attribute. Enclose all components within a set of double quotes, as collectively they are a single attribute value. For example: criteria="category='AutoDriver',objectDefi nition='VEHI'"

Tag attribute

Possible attribute value

Description

entity

"EntityName"

Type the name of the object from which you want the user to select a record. The user will be able to select from all available records, regardless of whether or not they are related to the main object record. For example, using entity="Account" allows the user to select any available Account. If the entity is a custom object, you must type entity="Project" and use the criteria tag attribute to identify the unique code of the custom object. For example:
criteria="objectDefinition='SDTX'".

criteria

Use any of the following components in the criteria attribute value:

category='DefaultCategoryName' (the name of the default category of the records you want available in the filter page)
objectDefinition='ProjectUniqueCode' (if the non-related object is a project, use this component to provide the unique code of the project whose records you want available in the filter page)
name='RecordName' (the name of the record you want available in the filter page)
numberstring='RecordNumber' (t he number of the record you want available in the filter page)

When using the entity tag attribute, you can specify criteria for which object records will be available to the user to select using the criteria tag attribute. This prevents all records in the system from being made available in the drop-down list in the filter page.

You can use any combination of the four components. For each component, you include the value that is desired in order for that record to be available to the user in the filter page.

When using the criteria tag components, you must use the following conventions:

Component values are enclosed by single quotes.
Type a comma between components when using more than one.
Do not type any spaces between items or between commas in this tag attribute.
Enclose all components within a set of double quotes, as collectively they are a single attribute value.
For example:
criteria="category='AutoDriver',objectDefi nition='VEHI'"

Header

<tc:filter name="SelectAccount" entity="Account" criteria="category='Office Reserve'" hidden="no" label="Please select an Account" displayString="Name;Number" displayFormat="* - *" />

Content

<tc:filter select="SelectAccount"> <tc:data select="Name" /> <tc:data select="DefaultCategory/Name" /> </tc:filter>

In this example, all Account records from the database that have the default category Office Reserve are listed in the filter page, so that the user generating the document can select an account. In the content section, the name and default category of the account that the user selected are retrieved and included in the generated document.

Main Filters and Sub-Filters

There are situations where you may want the user to select a record from which data must be retrieved, and this record is not directly related to the main object record. Instead, it is related to a related object of the main object. Or perhaps, you want the user to select a sub-object from a record that is related to the main object. You might even need the user to select a related object or sub- object of a record that is not related to the main object.

For example, if your main object is Policy, you may want the user to select parties Involved (a related object) in the Claim (a child custom object of Policy). This requires two filters: one to specify the Claim and one to specify the Involved.

Another example: you may want the user to select an address (a sub-object) of the contact selected in the Insured field (the contact-centric field) of a Policy (the main object).

These relationships sound complicated but they are not unusual. All of these situations require the use of multiple tc:filter tags, where one filter references another filter to indicate the desired relationship.

These filters are referred to as a main filter and a sub-filter. A sub-filter is a filter that references another filter, called a main filter, to indicate which object owns the sub-object that you are identifying.

Points To Remember

You must know the following points about main filters and sub-filters:

The main filter must be written before all of its sub-filters in the header section, so that the user first selects the record on which the sub-filters are based.
The main filter must allow the user to only select one record. You cannot use the multi="yes" tag attribute in the main filter tag.
The main filter can use searchCondition, test, or entity to identify the object record on which the sub-filter is based.
The sub-filter can use searchCondition or test to identify a related object or a sub-object of the record identified in the main filter.

The following table describes the tag attribute that is used in the main filter. Use this tag attribute in addition to the basic tag attributes noted in the tc:filter Tag Attributes table.

Tag Attribute for Main Filter

Tag attribute	Possible attribute value	Description
`usedBy`	"Integer"	Type the number of sub-filters that link to the main filter. Note: When the usedBy attribute is used, the objectFrom attribute must be used in a sub-filter.

Tag attribute

Possible attribute value

Description

usedBy

"Integer"

Type the number of sub-filters that link to the main filter.

Note: When the usedBy attribute is used, the objectFrom attribute must be used in a sub-filter.

The following table describes the attribute needed for tc:filter in the header section when defining the sub-filter. Use this tag attribute in addition to the basic tag attributes noted in the tc:filter Tag Attributes table.

Tag Attribute for Sub-Filter

Tag attribute	Possible attribute value	Description
objectFrom	"MainFilterName"	Type the exact name that you used for the main filter.

Related Object of a Related Object (Involved parties of Claim)

In this example, notice how the searchCondition of the main filter indicates which object it is pointing to: the Claim records of the Policy. The sub-filter is referencing the main filter, and the searchCondition attribute of the sub-filter is pointing to the Involved Parties of the Claim.

Header

Main filter

Sub-filter

<tc:filter name="SelectedClaim" searchCondition="Project" qualifier="Application_ProjObjectDefinition_UniqueCode=CLAM" label="Select the appropriate claim" displayString="Name;NumberString" displayFormat="* - *" usedBy="1" />

<tc:filter name="ClaimInvolvedParties" searchCondition="Involved" label="Please select the parties involved in this Claim" displayString="Contact/ FirstName;Contact/Name;DefaultCategory/Name" displayFormat="* * - *" multi="yes" objectFrom="SelectedClaim"/>

Content

<tc:filter select="SelectedClaim">

                <tc:data select="NumberString" />

                <tc:data select="Name" />

            </tc:filter>

            <tc:filter select="SelectedInvolvedParties">

                <tc:data select="Contact">

                <tc:data select="FirstName" />

                <tc:data select="Name" />

                </tc:data>

            <tc:data select="DefaultCategory/Name" />

            </tc:filter>

Sub-Object of a Related Object (Addresses of Involved Contact)

In this example, notice how the searchCondition of the main filter indicates which object it is pointing to: the Contact records of the Involveds. The sub-filter is referencing the main filter, and the test attribute of the sub-filter is pointing to the AddressList of the Contacts.

Header

Filter

Sub-filter

<tc:filter name="SelectedInvolvedContact" searchCondition="Involved_Contact" usedBy="1" displayString="FirstName;Name" label="Please select an involved" />

<tc:filter name="InvolvedContactAddress" objectFrom="SelectedInvolvedContact" test="AddressList" displayString="Type/Name;Street;City" displayFormat="* - * *" label="Please Select the Involved's Address." />

Content

<tc:filter select="SelectedInvolvedContact"> <tc:data select="FirstName" /> <tc:data select="Name" /> </tc:filter> <tc:filter select="InvolvedContactAddress"> <tc:data select="Type/Name" /> <tc:data select="Street" /> <tc:data select="City" /> </tc:filter>

Single-Option Filters

In certain circumstances, you will need to provide a filter page that only gives the user one record to select. This is necessary when you want the user to make a selection from a related object or sub- object of an object that is not the main object. For example, suppose you have a contact-centric custom object, Claim, and you want the user to select an address belonging to the contact that is selected in the contact-centric field for the Claim.

In this situation, you have to provide the user with a filter page where the user selects the contact record. This is the main filter, and it must be the only available option. In the next filter page, the sub- filter, the user selects the desired address from the list of addresses for that contact.

The main filter, which only provides one selection to the user, uses the test tag attribute of tc:filter to identify a single record, such as:

The parent custom object
The contact in the contact-centric field
The custom object record with which a task record is associated A scenario like this is demonstrated in the following example:

Header

Filter

Sub-filter

label="Please select the parent policy below." displayString="Name" displayFormat="*" usedBy="1" />

<tc:filter name="SelectedInvolveds" searchCondition="Involved" label="Please select the parties involved in the parent policy" displayString="Contact/ FirstName;Contact/Name;DefaultCategory/Name" displayFormat="* * - *" objectFrom="RetrieveParent" />

Content

<tc:filter select="SelectedInvolveds"> <tc:data select="Contact"> First Name: <tc:data select="FirstName" /> Last Name: <tc:data select="Name" /></tc:data> Role: <tc:data select="DefaultCategory/Name" /> </tc:filter>

In TeamConnect, the sub-filter indicates that it can display the Involved records of the parent Policy selected by the user in the main filter. In the content section, information about the Involved party, which the user selected in the filter page, appears in the generated document.