Template Items - a5-item Attribute

Description

Template Items are a powerful new way to efficiently add event handlers to the HTML markup used in the List template. Template items are added to the HTML markup by adding an a5-item attribute to the markup, as explained below.

Regardless of whether the List is defined as a free-form or columnar layout, every row displayed in the List is created by merging data into the row template. For a free-form List, there is a single template for the entire row and for a columnar List, there is a template for each column in the List. The template is HTML with placeholders for the List data.

For example, the template for the Firstname field in a columnar List might be:

{Firstname}

The template for a free-form List might be:

{<b>{Firstname} {Lastname}</b> <br>
{City} {State} {Zip}

You might want to add an event handler so that when the user clicks on the Firstname field, an event fires. You might change the template for the Firstname field to:

<span onClick="event1()">{Firstname}</span>

When the user clicks on the Firstname field in any row of the List, the event1() Javascript function should be called.

While inserting the onClick attribute into the that wraps the {Firstname} placeholder seems easy enough there are two problems with it:

  • The event will not be fired on a touch device

  • The event will be added to the DOM for every row in the List, which is very inefficient as there could be a large number of rows.

Both problems can be solved by using template items. The template could be defined as:

<span a5-item="item1">{Firstname}</span>

In the above example, 'item1' is the name of a template item. The event handlers for the 'item1' template item are defined in the Template Item editor.

To define template items, you can either click the Quick Access... button at the bottom of the List Builder window and then select 'Template Items' from the menu.

Or, you can click the Template 'items' hyperlink in the Column Template of Layout Template editor.

When you open the Template Items editor you get a screen that looks like this:

You can define as many template items as you want. For each item you define event handlers for the Click, Double Click and Right Click events.

You can also set the 'Selectable' property. If this property is set, then when the user clicks on the item, the row in which the user clicks is selected. Otherwise, the row is not selected.

When you insert a template item into the HTML markup you can insert an optional 'item argument'. The item argument follows the item name, delimited by a colon. In the example below, 'item1' is the item name and 'argumentValue' is the item argument. The purpose of the item arguments is to pass additional information to the Javascript event handler.

<span a5-item="item1:argumentValue">{Firstname}</span>

The Javascript event handlers for the item can reference:

Variable
Description
rowNumber

the row that was clicked (zero based)

ia

the item arguments (if any)

value

the value of the List

When you are editing the List template the Template 'items' hyperlink also gives you access to a special genie that makes it easy to insert items into the template: