APL Pager (APL 1.1 to 1.3)

(This is not the most recent version of APL. Use the Other Versions option to see the documentation for the most recent version of APL)

A Pager displays a series of components one at a time. Pagers are commonly used for displaying a time-ordered sequence of data items. A Pager differs from a Sequence because a Pager displays separate pages instead of a long, continuous strip.

Properties

The Pager component has the following properties in addition to the base component properties. See the meaning of the columns.

Property Type Default Styled Dynamic Description
data Array none No No Data to bind into this container.
firstItem Array of components and layouts none No No A component to include before all others.
initialPage Integer 0 No No The index of the starting page (0-based). Defaults to 0.
item(s) Array of components and layouts [ ] No No The Component(s) used to lay out the data set.
lastItem Array of components and layouts none No No A component to include after all others.
navigation normal, none, wrap, forward-only wrap No No Specifies the allowed navigation direction.
onPageChanged Array of commands [] No No Commands to run when the page changes

Pagers present themselves to the user as a series of pages arranged in a left-to-right order. The user typically swipes the pager left or right to change pages. On a device without a touchscreen, the pager moves based on keyboard input (left\/right\/tab).

A Pager behaves differently than a Sequence. A Sequence presents as a continuous list of items. On small screens, the Sequence may show just a single item when swiped slowly, but still support a faster swiping mode that rapidly advances through the content, and may show multiple small versions of the content in a "fast scroll mode". The individual items are displayed as immediately adjacent to each other. In contrast, a Pager presents its content as the new page replacing or fading in over the old page, often with a little motion in the swipe direction of both the old and new page.

The height and width of the Pager component default to 100dp if not specified. The height and width of a Pager must be either an absolute or relative dimension. You cannot use auto. The height and width of the children of a Pager are fixed at "100%".

When the Pager component is the target of an event, event.target reports the following values:

"event": {
  "target": {
    "disabled": Boolean, // True if the component is disabled
    "id": ID,            // ID of the component
    "uid": UID,          // Runtime-generated unique ID of the component
    "height": Number,    // Height of the component, in dp (includes the padding)
    "opacity": Number,   // Opacity of the component [0-1]
    "page": Integer,     // Current page
    "width": Number      // Width of the component, in dp (includes the padding)
}

data

An array of arbitrary data. If the data array is bound, the pager uses the data array inflation method.

firstItem

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

item(s)

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. If the data property is not assigned, the pager uses the simple array of child components inflation method.

lastItem

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

initialPage

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

The navigation property controls how the user may navigate with the content:

  • normal: Default. The user may move freely forwards and backwards in the pager.
  • none: The user may not move the pager. We assume that some automatic page advance mechanism will move the pages.
  • wrap: The user may move freely. The last page wraps around to the first page.
  • forward-only: The user may only move forward. This mode is intended for games or puzzles.

The SetPage and AutoPage commands can always move the pager. The navigation property only restricts what the user can do by swiping on the screen.

onPageChanged

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

"event": {
  "source": {
    "type": "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).

Sample Pager

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

Last updated: Nov 28, 2023