Introduction

Repeaters provide a way for you to add repeating content to a widget. Repeaters consist of repeating items, each with the same layout but different data.

For example, the repeater below contains three items, each with the same layout. There is an image on the left and two text elements on the right. However, the data in each item is different. That is, the actual images and text values are different in each repeated item.

The data displayed in a repeater comes from either:

• Connecting the repeater and the elements contained within its items to a dataset in the Editor.
• Using the data property in conjunction with the forEachItem(), forItems(), and onItemReady() functions in code.

Check out our Hello Repeaters example, which demonstrates how to use repeaters for websites. Since the functionality of repeaters for websites closely resembles that of repeaters for mobile app widgets, this example can be a valuable resource for helping you understand and become familiar with repeaters.

Repeated Item Template

Each 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. 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 using $w(), the global scope selector function.

Selector Scope

Selector functions are used to select specific elements so you can work with them in code. Depending on which selector you use, you are able to select elements from the different scopes described below.

There are two types of selector functions:

• Global Scope Selectors
• Repeated Item Scope Selectors

Global Scope

The $w() function that is available to your widget code selects elements in the global scope.

A selector with global scope can be used to select any element that is not contained in a repeater. You can also use it to select an element that is contained in a repeater, but you need to understand what that selection means.

When you select an element contained in a repeater from the global scope and you get the value of one of the element's properties, you receive the value of that element's property from the repeater's item template.

For example, here templateText is the text value of the myRepeatedText element from the repeater's item template.

When you select an element contained in a repeater from the global scope and you set the value of one of the element's properties or call one of the element's functions, the value is set or the function is called on the repeater's item template and all repeated instances of that element.

For example, here the item template is changed so that "New Text" is the text value of the myRepeatedText element. Also, all existing repeated items have the text value of their myRepeatedText element set to "New Text".

And here the item template is changed so that the myRepeatedMobileImage element is hidden. Also, all existing repeated items have their myRepeatedMobileImage element hidden.

Repeated Item Scope

There are two instances where you get a repeated-item-scope selector:

• The $item parameter of the forEachItem(), forItems(), and onItemReady() event handlers.
• When calling the $w.at() and passing it an event whose context is "COMPONENT_SCOPE". This is usually done in an event handler that handles event on an element inside a repeater.

A selector with repeated item scope can be used to select a specific instance of a repeating element.

For example, here when the myRepeatedMobileImage element is pressed, the value of a text element in the same repeated item where the mobile image was pressed is changed to "Selected". All the other text elements with the ID myRepeatedText in the other items of the repeater are not affected.

And here, when each item is ready, the value of a text element is set to a value found in that specific item's data.

You can also use a selector with repeated item scope to select non-repeating elements from the global scope. However, you cannot change a repeater's item template using a selector with repeated item scope.

You can restrict a selector with repeated item scope to only select elements from the current repeated items and their descendants, but not elements from the global scope by adding .scoped() to the selector so the function call looks like $item.scoped("#idToSelect").

Retrieve Repeater Item Data When Pressed

Each repeated item in a repeater has a MobileContainer element that holds all of its repeated elements. To retrieve the data associated with a specific repeated item when it is pressed, create an onPress event handler for the item's MobileContainer. Depending on how you populated the repeater with data, you either use the connected dataset or the repeater's data array to retrieve the pressed item's data in the event handler.

For a repeater populated by connecting it to a dataset:

For a repeater populated by setting its data property: