Velo Repeaters: The Lifecycle of Repeated Items

When working with a repeater using code, it is important to understand how the items in the repeater are created, updated, and deleted. But first, you need to understand the relationship in a repeater between its repeated items and its data. 

A repeater's data is stored as an array of objects. You get and set that array using the repeater's data property. Each object in the array must contain a unique _id property which is used to match the object's data to the individual repeated items of the repeater as described below. The value of the _id property can only be comprised of alphanumeric characters and hyphens (-). Other than _id, the objects in the repeater's data array can contain anything you want.

For example, a simple array of repeater data may look like this:

Repeater data is not automatically applied to the elements in the repeated items. You choose how to use the repeater's data in the onItemReady(), onItemRemoved(), forItems(), and forEachItem() callback functions. Most often, you will be applying the data of a repeated item to the properties and functions of the repeated elements contained in that repeated item.

For more information on these functions, see the API Reference.

Creating New Items

When you set a repeater's data property, new repeated items are created for each object that has an _id value that is not already present in the current array of data objects. The elements in the new items are first populated with the data of the repeater's item template. Then the onItemReady() event handler is triggered for each of the new items. Usually, you will overwrite some or all of the data populated from the item template in the onItemReady() event handler with the data for that specific item. When all of the onItemReady() event handlers have finished running, the new items are displayed.

For example, if the repeater's data property currently contains the following array:

And then you set its value to this array:

One new repeated item is created because an item with ID "2" did not yet exist. The onItemReady() event handler will run once for the new item. There you can set up its contents.

Updating Existing Items

When you set a repeater's data property, nothing occurs to repeated items whose IDs were already in the array of data objects, even if other data in the object has changed. To update repeated items with the new data, use the forEachItem() or forItems() functions.

For example, if the repeater's data property currently contains the following array:

And then you set its value to this array:

The content of elements in the exisitng repeated item will not change because an item with ID "1" already exists. To update the contents you need to call either the forEachItem() or forItems() functions.

Removing Items

When you set a repeater's data property, repeated items are removed if their IDs are no longer in the array of data objects. The onItemRemoved() event handler is triggered for each of the removed items.

For example, if the repeater's data property currently contains the following array:

And then you set its value to this array:

One repeated item is removed because an item with ID "2" no longer exists. The onItemRemoved() event handler will run once for the removed item.

Example

To demonstrate the full lifecycle of repeated items, we will use the following simplified example. 

The example has the following page elements:

• Three buttons:
  • The Add button adds more items to the repeater.
  • The Remove button removes the added items from the repeater.
  • The Update button updates the first item in the repeater.
• 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 two static arrays of data that we will use for the repeater.
• An onReady() function that:
  • Sets the initial data of the repeater.
  • Adds the event handlers that make the buttons work.
  • Adds the repeater onItemReady() and onItemRemoved() event handlers that run when new items are created and removed.

Scenario

We will now run through a simple scenario to demonstrate the complete item lifecycle.

When the page first loads, the onReady() function runs, setting all the event handlers mentioned above and setting the value of the repeater's data property to be the first array of sample data.

That means, when the page loads, the repeater's single item defined in the Editor will be replaced by two new items. The onItemRemoved() event handler does not run for the item that was removed because it was a static item defined in the Editor. However, the onItemReady() event handler runs for each of the new items that are added. In our case, we've defined the event handler to set the text values of the repeated item's elements from the corresponding data in the repeater's data array.

The repeater now looks like this:

If we then click the Add button, the repeater's data property is reset with a new array that contains the elements from both sample data arrays.

Because two of the elements in the data array are new, two corresponding new items are added to the repeater and the onItemReady() event handler runs once for each of these new items.

The repeater now looks like this:

If we then click the Remove button, the repeater's data property is reset back to the first array of sample data.

Because two of the elements from the data array are removed, the two corresponding items are removed from the repeater and the onItemRemoved() event handler runs once for each of these removed items.

The repeater now looks like this:

Finally, if we click the Update button, the repeater's data property is reset with an array with the same items as before, but with one value changed.

Because the IDs of the elements in the data array have not changed, nothing happens automatically. We need to manually call the forItems() function to update the elements in the corresponding repeated item.

The repeater now looks like this: