Pager (Character Displays)

A Pager displays a series of components one at a time. Pagers are commonly used for displaying a time-ordered sequence of data items like a slideshow.

Pager Example

{
  "type": "Pager",
  "items": [
    {
      "type": "Text",
      "text": "Text content shown on page #1"
    },
    {
      "type": "Text",
      "text": "Text content shown on page #2"
    }
  ]
}

Pager navigation on character displays

Character displays do not support touch input, so users cannot swipe to navigate through a Pager. Use the AutoPage and SetPage commands to progress through the pages.

Properties

The Pager has the following properties in addition to standard Component properties:

Property Type Default Dynamic Description
data Data <none> No Data to bind into this container
firstItem Array of components and layouts <none> No A component to include before all others
initialPage Integer 0 No The index of the starting page.
item(s) Array of components and layouts [] No The components used to inflate the data set.
lastItem Array of components and layouts <none> No A component to include after all others.
onPageChanged Array of commands [] No Commands to run when the page changes

Pagers present themselves to the user as a series of pages.

The height of the Pager defaults to 1 character if not specified. The width of the Pager defaults to 100% if not specified.

firstItem

If assigned, a single component/layout will be prepended to the pager using the single child inflation method (Single child inflation).

item (items)

An array of components and layouts to be displayed in the pager. If the data property is assigned, the pager uses the data-array inflation method (Data array inflation). If the data property is not assigned, the pager uses the simple array of child components inflation method (Simple child array inflation).

lastItem

If assigned, a single component/layout will be appended to the pager using the single child inflation method (Single child inflation).

initialPage

The index of the starting page to display. The index is 0-based and defaults to 0. If a firstItem is specified, that will be at index 0.

onPageChanged

The onPageChanged handler runs when the page has fully switched to a new page. The event generated has the following form:

"event": {
  "source": {
    "source": "Pager",
    "handler": "Page",
    "id": ID,          // ID of the pager
    "uid": UID,        // Runtime-generated unique ID of the component
    "value": NUMBER    // Index of the new page
  }
}

The event.source.value is set to the index of the new page (0-based index).

Was this page helpful?

Last updated: Nov 28, 2023