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 thetext
values of the text elements to values from the new item's corresponding data. If there is nocontent
value, the new item will have the default value given to it by the repeater's item template.
1
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.