SetPage Command (APL 2023.1 to 2023.2)

Changes the page displayed in a Pager component. The SetPage command finishes when the item is fully in view.

Properties

The SetPage command has the properties shown in the following table, in addition to the common command properties. Set the type property to SetPage.

In the following table, the "Default" column shows "Required" for properties that must have a value for the command to run. Otherwise it displays the default value, which might be none.

Property Type Default Description

componentId

Selector

:source

The Pager component.

position

relative, absolute

absolute

Whether the value is a relative or absolute offset. Defaults to absolute.

value

Integer

REQUIRED

The distance to move. Can be an absolute or relative value.

When there are N pages in the Pager component, the first is index 0 and the last has index N-1. A relative position offsets from the current page. For example, to move one page forward:

  {
    "type": "SetPage",
    "componentId": "myWeatherPager",
    "position": "relative",
    "value": 1
  }

An absolute position sets the index of the current page. A negative absolute position is an offset from the end of the list. For example, to go to the last page:

  {
    "type": "SetPage",
    "componentId": "myWeatherPager",
    "position": "absolute",
    "value": -1
  }

No intermediate pages display when switching between two pages (unlike a Sequence). For example, if the current page is 13 and SetPage runs with "position"="relative","value": 2, the current page transitions out and page 11 displays without showing page 12.

The SetPage command can set any page for display. It does not respect the allowed navigation direction in the Pager component. However, wrapping behavior affects page switch calculations, as shown in approximate algorithm.

Stopping a SetPage command jumps ahead to the target page if the SetPage command sequence is at least 50% complete, and it returns to the previous page if it is not at least 50% complete. The onPageChanged command runs one time when the command stops if the page has changed from the last page.

The SetPage command is ignored in fast mode.

componentId

A selector that identifies the Pager to update. When not provided, defaults to :source. The :source selector targets the component that issued the SetPage command.

position

If the position is relative, the value is a relative distance to move from the current page. If the position is absolute, the value is the absolute page number to which the display will move.

value

The value is either the distance to move or the absolute page number to move to.

The algorithm to calculate final position and direction can be approximated with this pseudo-code.

  if (command.position == 'absolute') {  // Absolute motion
    let index = command.value < 0 ? pager.children.length + command.value : command.value;
    index = Math.max(0, Math.min(pager.children.length - 1, index));  // Clamp range

    // Return the final index and the direction of motion
    if (index == pager.currentIndex)
      return NO_MOVE

    return (index, index < pager.currentIndex ? "LEFT" : "RIGHT");
  }
  else {  // Relative motion
    let index = pager.currentIndex + command.value;

    // If relative motion goes out of bounds and we don't support wrapping, ignore the command
    if (pager.navigation != "wrap" && (index < 0 || index >= pager.children.length))
      return NO_MOVE;

    // Wrap appropriately
    index = ((index % pager.children.length) + pager.children.length) % pager.children.length;
    if (index == pager.currentIndex)
       return NO_MOVE;

    return (index, command.value < 0 ? "LEFT" : "RIGHT");
  }

The pager animation is driven by the returned direction.

This algorithm has these characteristics:

  • Absolute values clamp within the valid range of pages. The direction is relative to the current page.

  • Relative values on a wrapping pager will wrap arbitrarily. The direction is based on the commanded value, and wrapping doesn't change the direction.

  • Relative values on a non-wrapping pager that go out of range are ignored.

Reinflation strategy

When the Reinflate command runs, the SetPage command can resume after Alexa reinflates the document. The command resumes when it runs on a sequencer that is specified in the preservedSequencers array on Reinflate. The command saves the index of the target page.

If the target component is not a Pager component in the reinflated hierarchy, the command is ignored.

If a page transition is running when Alexa reinflates the document, the target page renders when reinflation completes. This has the same effect as preserving the pageIndex (see preserve).

When preserving the SetPage command, the experience works best when both of the following are true:

  • The data source for the Pager has the same number of elements before and after reinflation
  • The Pager content remains at the same indicies.

If the number of elements, or the content at the original indicies change during reinflation, users might find the experience jarring.

Was this page helpful?

Last updated: frontmatter-missing