APL Pager

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.

About the Pager component

A Pager displays as a series of pages. The pages display in either a horizontal or vertical direction:

  • Horizontal – The pages display in either a left-to-right or right-to-left order, depending on the value of the layoutDirection property. When the Pager is configured to allow user navigation, the user swipes the component left or right to change pages.
  • Vertical – The pages display in a top-to-bottom order. When the Pager is configured to allow user navigation, the user swipes the component up and down to change pages.

On a device without a touchscreen, the pager moves based on keyboard input (left/right/tab or up/down/tab).

You can programmatically change pages in the Pager with the SetPage command. You can also configure the Pager to prevent users from changing the pages with the navigation property.

A Pager is different than a Sequence. A Sequence presents as a continuous list of items. On small screens, the Sequence might show one item when swiped slowly, but the Sequence still supports a faster swiping mode to rapidly advance through the content. When the Sequence items are small, the Sequence can show multiple small versions of the content in a "fast scroll mode." The individual items display next 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.

Properties

The Pager component has the following properties:

Property Type Default Styled Dynamic Description

handlePageMove

Array of page move handlers

[]

No

No

Handlers to run when the Pager changes pages. Use to create custom visual page transitions.

initialPage

Integer

0

No

No

The index of the starting page (0-based). Defaults to 0.

navigation

One of normal, none, wrap, forward-only

wrap

No

Yes

Specifies the allowed navigation direction.

onPageChanged

Array of commands

[]

No

No

Commands to run when the page changes

pageDirection

One of horizontal, vertical

horizontal

No

Yes

The direction to move pages

preserve

Array of string

[]

No

No

Properties to save when reinflating the document with the Reinflate command.

When the Pager is the source or target of an event, the following values are reported in event.source or event.target:

{
  // Pager-specific values
  "type": "Pager",
  "page": Integer,     // Current page

  // General component values
  "bind": Map,         // Access to component data-binding context
  "checked": Boolean,  // Checked state
  "disabled": Boolean, // Disabled state
  "focused": Boolean,  // Focused state
  "height": Number,    // Height of the component, in dp (includes the padding)
  "id": ID,            // ID of the component
  "opacity": Number,   // Opacity of the component [0-1]
  "pressed": Boolean,  // Pressed state
  "uid": UID,          // Runtime-generated unique ID of the component
  "width": Number      // Width of the component, in dp (includes the padding)
}

height and width

The height and width of the Pager component default to 100 dp when not specified. The height and width of a Pager must be either an absolute or relative dimension. You can't use auto.

The height and width of the children of a Pager are always 100%. This means that a Pager child item is always the same size as the Pager itself.

layoutDirection component property

The component layoutDirection property determines the order of the pages when pageDirection is horizontal:

  • Left-to-right (LTR) – The Pager arranges pages in left-to-right order. The user swipes from right to left to go forward to next page.
  • Right-to-left (RTL) – The Pager arranges pages in right-to-left order. The user swipes from left to right to go forward to next page.

The layoutDirection property also determines how the handlePageMove handler works. For details, see handlePageMove.

handlePageMove

Specifies an array of page move handlers. These handlers run as the Pager moves from one page to the next. When handlePageMove contains a value, the handlers override the normal visual page-changing behavior.

The event generated by a handlePageMove handler has the following form.

"event": {
  "source": {
    "type": "Pager",
    "handler": "Move",
    ...                   // Component source properties
  },
  "direction": STRING,    // Direction of motion.  One of 'left', 'right', 'up', or 'down'
  "forward": BOOLEAN,     // True if the pager is moving forward.
  "amount": NUMBER,       // Number between 0 and 1.
  "currentChild": {       // Properties of the component that is currently on the screen
    "id": ID,
    "uid": UID
  },
  "nextChild": {          // Properties of the component that is being moved onto the screen
    "id": ID,
    "uid": UID
  }
}

Refer to Event source for a description of event.source properties.

The handlePageMove handler runs in fast mode.

The direction property in the event indicates the direction of motion of the gesture. The meaning of the direction depends on the layoutDirection property:

  • Left-to-right (LTR) – A direction value of left or up navigates from the current page to the next page in the list of pages. A direction value of right or down navigates from the current page to the previous page in the list of pages.
  • Right-to-left (RTL) – A direction value of right or up navigates from the current page to the next page in the list of pages. A direction value of left or down navigates from the current page to the previous page in the list of pages.

When you create a custom animation to transition between pages, the animation isn't required to match the gesture motion.

The amount field is the distance moved through the gesture. An amount of zero means that the current page should display fully on the screen and the next page should't display. An amount of one means that the current page should be fully removed and the next page should be positioned appropriately on the screen. Use the amount value to set properties such as opacity and transform to create animations that match the user's gestures.

A single page move handler is an object with the properties shown in the following table.

Property Type Default Description

commands

Array of commands

[]

Commands to run when the Pager invokes this handler.

description

String

""

Optional description of the handler.

drawOrder

One of nextAbove, nextBelow, higherAbove, higherBelow

higherAbove

Stacking order of the pages.

when

Boolean

true

When true, invoke this handler

Alexa checks the array of move handlers in order and invokes the first move handler with a true when clause. Invoking a handler runs the commands defined in that handler. If no move handlers have a true when clause, Alexa runs the system default move handler.

The drawOrder property controls which page to display on top during the transition. Use this property when your custom transition overlaps the pages. The following tables shows which page is on top (either "current" or "next") for a given motion direction and drawOrder.

Motion direction nextAbove nextBelow higherAbove higherBelow

Going forward in the list

  • left (when layoutDirection is LTR)
  • right (when layoutDirection is RTL)
  • up

Next

Current

Next

Current

Going backward in the list

  • right (when layoutDirection is LTR)
  • left (when layoutDirection is RTL)
  • down

Next

Current

Current

Next

During the handler calls, the base position of the current and next components are set to the bounds of the Pager and each has opacity set to 1. The handlePageMove handler must apply appropriate transformations and opacity changes to visually position the current and next pages.

The following example simulates the standard pager behavior. When changing pages, the current page slides out of view and the new page slides into view.

{
  "handlePageMove": [
    {
      "when": "${event.direction == 'left' || event.direction == 'right'}",
      "drawOrder": "higherAbove",
      "commands": [
        {
          "type": "SetValue",
          "componentId": "${event.currentChild.uid}",
          "property": "transform",
          "value": [
            {
              "translateX": "${100 ` event.amount ` (event.direction == 'left' ? -1 : 1)}%"
            }
          ]
        },
        {
          "type": "SetValue",
          "componentId": "${event.nextChild.uid}",
          "property": "transform",
          "value": [
            {
              "translateX": "${100 ` (1.0 - event.amount) ` (event.direction == 'left' ? 1 : -1)}%"
            }
          ]
        }
      ]
    }
  ]
}

When building a custom page transition animation, note the following:

  • Use the event.direction property to determine the direction the user dragged the pager.
  • Set the drawOrder to position one page above or below the other page. You can ignore this property if the pages don't overlap.
  • Call SetValue to change each visual property you want to use based on the current value in event.amount. For example, change opacity to fade a page in or out, and change transform to slide a page on or off the screen.
  • Make sure that the end of the page move sets the visual values appropriately:
    • The opacity of the event.nextChild must be 1 to be fully visible.
    • Any transform property of the event.nextChild must be back to normal.

The following example shows handlePageMove that use opacity and transform. When advancing through the pager, the change to the transform property on the new page causes the page to slide in from the right. The changes to the transform and opacity properties on the old page cause that page to shrink and fade out as the new page slides into view. For debugging purposes, a Text component at the top of the viewport displays the value of event.amount.

The handlePageMove handler commands run when the pager transitions between two pages. The commands don't run in the following scenarios:

  • The pager has no pages or has a single page.
  • The navigation property is none and the user tries to drag the page.
  • The user tries to drag the page in a direction that isn't supported by the navigation property. For example, when navigation is forward-only, swiping right or down doesn't change the page.
  • The user tries to drag the page in the direction not specified by pageDirection. For example, when pageDirection is horizontal, swiping up or down doesn't change the page.

initialPage

The index of the starting page to display. The index is 0-based and defaults to 0. When the firstItem property has a value, the firstItem item is at index 0.

The navigation property controls how the user navigates the content:

  • normal – The user can move freely forwards and backwards in the pager.
  • none – The user can't move the pager. Use commands to programmatically move the pager. For example, use the AutoPage and SetPage commands.
  • wrap – The user can move freely forwards and backwards. When the user swipes on the last page, the pager wraps to the first page.
  • forward-only: The user can move forward but not backwards.

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

onPageChanged

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

"event": {
    "source": {
      "type": "Pager",
      "handler": "Page",
      ...                     // Component source properties
    }
  }

Refer to Event source for a description of event.source properties. The event.source.value property contains the index of the new page (0-based index).

pageDirection

Determines the direction of the animation when pages change. The pageDirection also determines the direction users swipe the screen to navigate the pager.

The pageDirection can be horizontal or vertical:

  • horizontal – (default) The user must swipe left or right to navigate the pages. Swiping to the left advances to a higher-index page. Swiping to the right goes back to a lower-index page. The default animation shows the pages sliding to the left or right as they change.
  • vertical – The user must swipe up or down to navigate the pages. Swiping up advances to a higher-index page. Swiping down goes back to a lower-index page. The default page-change animation shows the pages sliding up or down as they change.

preserve

An array of dynamic component properties and bound properties to save when reinflating the document with the Reinflate command.

A Pager has the following component-specific property names you can assign to the preserve array:

  • pageId – Set the starting page to match the ID of the current page.
  • pageIndex – Set the starting page to the index of the current page.

If none of these values are specified, the starting page is the after reinflating the document is initialPage.

If you set preserve to pageId, but the currently displayed page of the pager doesn't have an id set, the starting page after reinflating the document is initialPage instead. Similarly, if the specified pageIndex can't be (for example, if the number of pages changes), the initialPage index is used.

The following example restores the current page of the Pager after reinflating the document.

{
  "type": "Pager",
  "id": "MyPager",
  "preserve": ["pageIndex"]
}

Actionable properties

A pager is an actionable component. The pager inherits all the actionable properties.

Multichild properties

A pager is a multichild component. The pager inherits all the multichild properties.

Sample Pager

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