Velo Repeaters: About Repeater Item Templates

A repeater has an item template that contains the elements and initial data that are used when new items are created. The template's initial state is the state of the first repeated item that appears in the Editor. When new repeated items are created, the values of the repeated elements are set to the values from the item template by default. You can then override those default values by connecting the repeated items to a dataset or by using the onItemReady() event handler that runs when new items are created.

Using code, you can set the properties of, get the properties of, or call functions on the elements of the item template by selecting the elements from the global scope with the $w() function.

Example

To demonstrate how the item template affects your items and how you can change the item template with code, we will use the following simplified example.

The example has the following page elements:

  • Two buttons:
    • The Add next item button adds an item to the repeater from a static array of data.
    • The Change content globally button changes the repeater's item template by setting a value in one of its element's properties from a global scope selector.
  • A repeater where each repeated item in the repeater contains two text elements:
    • The text element on the left shows the item's ID.
    • The text element on the right shows the item's content.

The example has the code shown below that:

  • Defines the static data that will be used in the repeater.
  • Defines an onReady() event handler that:
    • Sets the initial data of the repeater to be an empty array.
    • Adds the event handlers that make the buttons work.
    • Adds a repeater onItemReady() event handler, which runs when new items are created. It sets the text values of the text elements to values from the new item's corresponding data. If there is no content value, the new item will have the default value given to it by the repeater's item template.
Copy

Scenario

We will now run through a simple scenario to demonstrate how the item template is used.

When the page first loads, the onReady() function runs, setting all the event handlers mentioned above and clearing out the repeater's data. That means, when the page loads, you won't see the repeater at all. Remember, the initial values for the item template are defined in the Editor. That means the text value of the repeatedText element in the item template is now Original template text.

If we then click the Add next item button, the first element from the data array ({"_id": "1", "content": "First item"},) is added to the repeater. Since the first element contains values for the _id and content properties, the onItemReady() event handler will assign these values to the repeated elements of the new item, overwriting the default values from the item template.

The repeater now looks like this:

And the text value of the repeatedText element in the item template is Original template text.

If we then click the Add next item button again, the second element from the data array ({"_id": "2"}) is added to the repeater. Since the second element does not contain the content property, the onItemReady() event handler does not assign a value to the text property of the new item's repeatedText element. So the default text value from the item template is not overridden.

The repeater now looks like this:

And the text value of the repeatedText element in the item template is still Original template text.

If we then click the Change content globally button, which selects the repeatedText element using a global scope selector, the text value of the repeatedText elements in the current repeated items will change. Because the repeatedText element was selected with a global scope selector, changing its text value also changes the value in the item template.

The repeater now looks like this:

And the text value of the repeatedText element in the item template is now New template text.

If we then click the Add next item button, the third element from the data array ({"_id": "3", "content": "Third item"}) is added to the repeater. Since the third element contains values for the _id and content properties, the onItemReady() function will assign these values to the repeated elements of the new item, overwriting the default values from the item template.

The repeater now looks like this:

And the text value of the repeatedText element in the item template is still New template text.

Finally, if we click the Add next item button again, the fourth element from the data array ({"_id": "4"}) is added to the repeater. Since the fourth element does not contain the content property, the onItemReady() event handler does not assign a value to the text property of the new item's repeatedText element. So the default text value from the item template is not overridden.

The repeater now looks like this:

And the text value of the repeatedText element in the item template is still New template text.

Tip: Adding items to the repeater might affect your page layout.

Did this help?