How to Define a Hyperlink in a Client-side Template

Description

Client-side template syntax is used in Lists, FormView, and ViewBox controls to define the control's layout. If you want to include hyperlink in the template definition, you must stop the hyperlink HTML element's click event from bubbling up to the top-level control.

There are two ways to add hyperlinks to the HTML markup you define for the client-side template:

a5-item

Using the special a5-item attribute in the hyperlink HTML (these are called Template items.)

event handlers

Add event handlers (eg, onclick, ontouchstart, etc) to the hyperlink HTML.

 Using the 'a5-items' Attribute

  •  Defining an a5-item in a List Control

    1. Click the Template 'items' hyperlink on the List Layout tab and select Define/edit template items to open the Define Items dialog to define a new Template Item.

      Click the "Define/edit template items" option to create new or edit existing Items.
    2. In the Define Items dialog, click the Add Item button to add a new a5-item. Give the item a unique Item name. This name will be referenced in your client-side template in the a5-item property.

      In the image below, an a5-item called "item1" has been created. In the onClick property, javascript was added to emit the value of the argument passed to the a5-item (code listed below). Arguments can be passed to an a5-item as either a string or a JSON object.

      Javascript defining item1's onClick event
      var arg1 = ia;
      alert("Argument is " + arg1);
      The a5-item, "item1", displays the value of the argument passed to the item when the onClick event occurs.
    3. Define your hyperlink and add the a5-items attribute to the markup. For example, if the item's name is "item1" and takes one argument, "alpha", the following template code would add the a5-item to a hyperlink:

      <a a5-item="item1:alpha" href="#">Click me</a>
  •  Defining an a5-item in a FormView or ViewBox Control

    1. Click on the Items tab in the builder and define a new a5-item. Click the Add Item button to create a new a5-item.

      The Items tab in the FormView Builder.
      The Items tab in the ViewBox Builder.
    2. Once you have created your a5-item, you can add it to your hyperlink via the a5-item attribute. For example, if the item's name is "item1" and takes one argument, "alpha", the following template code would add the a5-item to a hyperlink:

      <a a5-item="item1:alpha" href="#">Click me</a>

 Adding Event Handlers to the Hyperlink HTML

In order to add hyperlinks to the HTML markup that you define for a client-side template in a List, FormView, or ViewBox control, you need to add special event handlers to tha anchor tag's onclick and ontouchstart events to prevent the event from bubbling up to the control itself. Otherwise, the control will handle the event and ignore the hyperlink.

For example, you might add some HTML markup to the template that navigates to an external webpage:

<a href="http://www.google.com" target="_blank">Click me</a>

When you run the component and tap on the hyperlink, nothing will happen. This is because the event is bubbling up to the control and the control is ignoring the event. However, if you change the markup to stop the event from propagating to the control, tapping (or clicking) the hyperlink will work as expected:

<a href="http://www.google.com" 
    target="_blank"
    onclick="$e.stopPropagation(event);"
    ontouchstart="$e.stopPropagation(event);">Click me</a>