This article describes a feature available in Enterprise subscription plans.
When editing some fields a Template drop-down is available to choose from pre-set templates. In the Title field these allow you to choose to display the title as a H3, H2 and so forth.
Click the Pencil icon next to the drop down to launch the Template Editor. This code editor provides access to the Handlebars template used to display the selected field. The editor is pre-populated with the code in the selected template. You can not modify the system-provided templates, but you can copy them and create our own custom templates.
To make your own custom template make any code changes and click Save.
A common use of the Template Editor is to introduce conditional logic into the output. Examples include:
If the phone field is empty, display a default phone number
If the result is in the Gold category, display a link to their Website and a direct phone number
If the result has the type = Person display a link to their Biography
If the result has type = Dealer, display only categories in the Dealer group
If the result has a description longer than 100 characters, display a link to the detail page.
And so forth. The above examples all illustrate field-level logic. The logic itself can involve any attribute of the result, so the Title template can check if the result has an image provided, for example.
Location Fields
The field template is passed the location object. This allows for any result fields to be displayed as {{ fieldname }}. The exact list of fields varies by each customer, but you can see each field under Data > Fields. Field names with spaces are reduced to their "safe" representation, which can be viewed under Data > Fields > Field Name > Field Details and the Template Markup shows the proper representation.
In addition to the location data fields, the following attributes are available:
{{ml_offset}} # The numeric offset of the result starting with 0
{{ml_number}} # The result number starting with 1
{{ml_zebra}} # A value that toggles between 1 and 0, useful for creating striped rows.
{{ml_priority}} # If set, the result is prioritized
{{ml_language}} # An object with all language constants for the active language, e.g. {{ml_language.LOCATOR_SELECT}} becomes Please Select... in the default language file
{{ml_territory_match}} # Set to 1 if the result is a territory-based result.
{{ml_taglist}} # All ID-indexed array of all active categories
{{tagidlist}} # An array of category IDs for the location
{{ml_location_tags}} # An array of category objects for the location
{{ml_user}} # The currently logged-in user id
{{ml_search_form}} # An object that represents the current state of the search form
{{ml_paginaton_total}} # The length of the current result list, typically the size of the results page
Search Form State
In addition to the attributes of individual locations, the state of the search form is also exposed to the field templates. This can be used to change results display based on the search. For example, to highlight the category if the user searched for it.
{{#if_in_array 43 ml_formstate.tags}}
User searched for Tag with ID 43!
{{/if_in_array}}
Display the keyword the user searched for
{{#if ml_formstate.keyword}}
You searched for {{ml_formstate.keyword}}
{{/if}}
Programming in Field Templates
Most templates already have some Handlebars logic in them. The first in the screenshot above shows the system checking to see if the Title field has a value, and if it does, output the Title and related markup, otherwise, it does nothing.
{{#if title }}
...
{{/if}}
Example: Looping over categories
Loops can be executed through the handlebars "each" command. See the Taglist templates found under the "Category List" field to see examples of looping through categories:
{{#each tagidlist}} # for each category
{{#with (lookup ../ml_taglist this)}} # get the full category object
{{#if category_link}} # if the category_link is set, output a link
<a href="{{category_link}}" target="_blank">
{{/if}}
{{/with}}
{{/each}}
Example: Check if a location is in a category
Checking if a location has a particular category can be done as follows:
{{#if_in_array 229 tagidlist}} This location has category with ID 229 {{/if_in_array}}
This can be used to conditionally show or hide data based on what categories the location is assigned to.
Text Fields
Each system and custom field comes with a default field template, but users can also can also create a template that isn't attached to a specific field. Add a "Text" field to the List, Details, Map or Search Form as shown below. The Text template is a great place to author custom logic or to combine the output of multiple fields into a single field.
Accessing Field Settings
When a template is customized, it is disconnected from the settings of the field in the Interface Builder. For example, the Label, Tooltip and Styles options of the Full Address field no longer control the corresponding settings values in the customized template as shown below. Once the template is customized, the Interface Builder no longer attempts to insert those configuration options dynamically.
To retain the ability to leverage Interface Builder settings in a custom template, the ml_field_setting handlebars helper can return the current setting's value. The below will return the field setting of the 'display-class' setting, for example:
{{ml_field_setting 'display-class' }}
In the below example, we have customized the template for the Title field, yet retained the ability to configure the Styles option by inserting the ml_field_setting helper into the H3 class attribute:
Other common settings values are:
Label as
{{ml_field_setting 'label' }}Tooltip as
{{ml_field_setting 'tooltip' }}Icon as
{{ml_field_setting 'cssiconclass' }}Link Text as
{{ml_field_setting 'innertext' }}
Managing Templates
When you edit a system template (E.g. the name does not start with User), when you click save, the system will create a User Template based on the system template and make it active. As shown below, the user edited the Label, clicked Save and now the User Label is active and available for edit.
To create another new user-defined label, repeat the same process by choosing Label, clicking Edit and saving. The new user defined template will include a (2).
User Templates are available system-wide, meaning they can be shared between interfaces. Edits to a user field template used in multiple interfaces will affect any interface that uses that same field template.