APL Backstack Extension

Use the backstack extension to give users the ability to navigate back to previously-view APL documents, similar to the HTML_History object.

The backstack extension is available on Amazon devices, but might not be available on all devices devices that support APL. Use the when property in your APL document to provide an alternate experience for devices that don't support backstack.

For details about how extensions work, see Extensions.

Extension summary

Backstack extension overview

Similar to the HTML_History object, the backstack extension allows for implicit sequential back navigation to previous documents, while also preserving state of those documents. The backstack extension adds new commands so that documents can directly manipulate the backstack and return to previous documents.

• The backstack extension is an optional feature, and might not be available on all devices that support APL.
• The backstack extension is relative to a single instance of an APL client. This is similar to HTML_History being relative to an individual tab in a browser.
• Documents are added to the backstack on an opt-in basis, by providing a backstackId in the document settings.
• The backstack can be used to return to previous documents in the stack, but can't go forward.
• The backstack length can be queried using the backstack property in the environment property.
• Documents in the backstack are implicitly returned to in reverse sequential order. They can be returned to non-sequentially through explicit use of their backstackId.
• The backstack preserves and restores the state of documents returned to via back navigation.
• The backstack implicitly clears all subsequent documents on return to any previous document in the stack.
• The backstack can be explicitly cleared with the Clear command.

Understand the backstack

To use the backstack extension, request the extension in the document extensions property.

The URI for the backstack extension is "aplext:backstack:10".

This example requests the backstack extension and assigns it the name "Back".

{
  "type": "APL",
  "version": "2022.2",
  "extensions": [
    {
      "name": "Back",
      "uri": "aplext:backstack:10"
    }
  ]
}

Use the environment.extension variable to check whether the user's device supports the backstack extension.

{ "type": "Text", "text": "The backstack extension is ${environment.extension.Back ? 'installed' : 'not installed'}" }

When you reference backstack in your document, always use the when clause with the environment.extension variable to make sure that the extension is supported on the user's device.

Add documents to the backstack

By default, APL documents are not added to the APL client’s backstack (even when you request the backstack extension).

To include a document on the backstack, set the backstackId property in the document settings property for the document.

{
  "type": "APL",
  "version": "2022.2",
  "extensions": [
    {
      "name": "Back",
      "uri": "aplext:backstack:10"
    }
  ],
  "settings": {
    "Back": {
      "backstackId": "myDocument"
    }
  }
}

For more details on the requirements for targeting a document in the backstack, see the GoBack command.

Navigate the backstack

There are 2 ways that a user can navigate documents you have added to the backstack:

1. Implicit (System Event) back navigation
2. Explicit (Command Based) back navigation

Any navigation of the backstack implicitly clears the document being returned to, and all subsequent documents from the backstack, regardless of how navigation took place (implicit or explicit).

For example, assume documents A,B,C, & D have been added to the backstack. The user navigates back to document B. This removes B,C,& D from the backstack and only document A remains.

System event back navigation

A system back event is considered any event performed by the device’s OS in response to user back input. This may include inputs such as:

• Press of a physical back button on the device or paired remote control.
• Press of a system-level UI back button (Android system tray).
• The user saying an utterance such as ‘back’ or ‘go back.’

On handling of a system back input event, the APL client follows these rules:

• When the backstack property length is greater than zero, the current document is exited, and the previous document in the stack is restored. This is the same as running the GoBack.
• When the backstack property lengthis zero, the current document AND the client is exited. This is the same as running the [Finish] command.

Command-based back navigation

The backstack extension provides support for explicit navigation of the backstack via the GoBack command. Run the GoBack command from any event handler to navigate the backstack in reverse sequential order. Assuming that the backstack extension has been registered as 'Back', send a GoBack command with:

{
  "type": "Back:GoBack"
}

Command-based back also allows for non-sequential navigation of the backstack through use of the backType property on the GoBack command.

{
  "type": "Back:GoBack",
  "backType": "id",
  "backValue": "myDocument"
}

In certain device use cases a system-level back input may not be available. The backstack environment property responsibleForBackButton can be queried to determine if the APL document is responsible for providing input to the backstack (because the system is not). When true, you can use the GoBack command for back navigation.

For example, an APL document using the backstack can draw its own 'back' button on the screen if the system-level back input is not available:

{ "when": "${environment.extension.Back.responsibleForBackButton}", "type": "TouchWrapper", "items": { "type": "Text", "text": "Press here to go back" }, "onPress": { "type": "Back:GoBack" } }

Clear the Backstack

Use the Clear command to explicitly clear the backstack. Run the Clear command from any APL event handler:

{
   "type": "TouchWrapper",
   "items": {
     "type": "Text",
     "text": "Clear the backstack"
   },
   "onPress": {
     "type": "Backstack:Clear"
   }
 }

Restore the document state from backstack

When returning to any document in the backstack, the document restores to the last active state before the document was exited and added to the backstack. In addition to standard rules of document inflation, the following rules apply:

• All dynamic component properties are restored to their last active value.
• All component stated properties are restored to their last active value.
• Focus returns to the last component to have focus.

• All navigable components are restored to their last active ‘positions’:

  • GridSequence – last scroll position.
  • ScrollView – last scroll position.
  • Sequence – last scroll position.
  • Pager – last active page.
• All media components are restored to their last active states:
  • Video – All video state properties are restored.
• onMount handlers don't run when the backstack restores the document.

Note that any commands active when the document was exited are not restored.

Settings

The backstack extension has the following settings.

backstackId

The backstackId property determines whether the document is added to the backstack.

A document is added to the backstack when the document is replaced by a new document, not when the document is initially displayed on the screen. For example:

1. APL initializes and displays document A, which has a backstackId set.
2. Backstack length is 0.
3. The device receives and displays document B.
4. Backstack length is now 1, because document A has been added to the stack.

If the backstackId is not present or empty, the document will not be added to the backstack. If it is present, the document is added to the backstack.

There is no requirement that backstackId values be unique; duplicate backstackId values are permitted in the backstack. Be aware that with duplicates only the most recent document in the backstack can be reached with the GoBack command.

For example, to indicate a document should be added to the backstack, specify:

{
  "type": "APL",
  "version": "2022.2",
  "extensions": [
    {
      "name": "Back",
      "uri": "aplext:backstack:10"
    }
  ],
  "settings": {
    "Back": {
      "backstackId": "myDocument"
    }
  }
}

Note that the name of the settings property matches the name assigned to the backstack extension in the extensions property.

Environment

The backstack extension adds the following environment properties in the assigned namespace:

These properties are added to the environment properties in environment.extension.

The following example requests the extension with the name "Back". Therefore, the environment properties are available in environment.extension.Back.

{
  "type": "APL",
  "version": "2022.2",
  "extensions": [
    {
      "name": "Back",
      "uri": "aplext:backstack:10"
    }
  ],
  "mainTemplate": {
    "item": {
      "type": "Container",
      "bind": {
        "name": "Responsible",
        "value": "${environment.extension.Back.responsibleForBackButton}"
      },
      "firstItem": {
        "type": "Text",
        "text": "There are ${environment.extension.Back.backstack.length} items on the back stack"
      },
      "data": "${environment.extension.Back.backstack}",
      "items": {
        "type": "Text",
        "text": "Backstack ${index}: '${data}'"
      },
      "lastItem": {
        "type": "Text",
        "text": "The back button ${Responsible ? 'should' : 'should not'} to be drawn"
      }
    }
  }
}

backstack

The backstack array contains the identifiers for all of the previously visited documents that had non-empty backstackId values. The array is sequentially ordered, wherein the first document visited is at index 0 and the most recent document visited is at index length-1. An empty array indicates that there are no documents in the backstack.

This can be used to query the length of the backstack for conditional logic relative to the display of a custom back button:

{
  "type": "APL",
  "version": "2022.2",
  "extensions": [
    {
      "name": "Back",
      "uri": "aplext:backstack:10"
    }
  ],
  "mainTemplate": {
    "item": {
      "type": "TouchWrapper",
      "when": "${environment.extension.Back.backstack.length > 0}",
      "item": {
        "type": "Text",
        "text": "Go Back!"
      },
      "onPress": {
        "type": "Back:GoBack"
      }
    }
  }
}

responsibleForBackButton

The responsibleForBackButton property is true on devices that don't have a standard system back button. Most devices have some common system-defined method of invoking back by pressing a keyboard or remote control button, using a standard system-defined gesture (such as swiping on the screen) or by displaying a back navigation button in a status bar. A few devices (such as the original Echo Show) rely on the displayed APL application to show an appropriate back button if needed. In those cases the APL document should be prepared to render a suitable visual experience:

{
  "type": "APL",
  "version": "2022.2",
  "extensions": [
    {
      "name": "Back",
      "uri": "aplext:backstack:10"
    }
  ],
  "mainTemplate": {
    "item": {
      "type": "TouchWrapper",
      "when": "${environment.extension.Back.responsibleForBackButton}",
      "item": {
        "type": "Text",
        "text": "Go Back!"
      },
      "onPress": {
        "type": "Back:GoBack"
      }
    }
  }
}

Commands

The backstack extension adds two new commands:

• GoBack
• Clear.

GoBack

The GoBack command returns to a previous document in the backstack. It has the following properties:

An example of the GoBack command that can return to any previous document in the backstack.

{
  "type": "APL",
  "version": "2022.2",
  "extensions": [
    {
      "name": "Back",
      "uri": "aplext:backstack:10"
    }
  ],
  "mainTemplate": {
    "item": {
      "type": "Container",
      "data": "${environment.extension.Back.backstack}",
      "item": {
        "type": "TouchWrapper",
        "item": {
          "type": "Text",
          "text": "Go to document id ${data}"
        },
        "onPress": {
          "type": "Back:GoBack",
          "backType": "id",
          "backValue": "${data}"
        }
      }
    }
  }
}

backType

The type of back navigation to use. The backType property is an enumerated value with the following options:

When used in combination with the backValue property, the backType allows for navigation of the backstack by count, index, or id.

backValue

The backValue property is the value of the document to return to in the backstack depending on the provided backType.

When the backType is count or index, the backValue expects an integer value for navigating the backstack array.

For example, assume the backstack contains the documents [ "A", "B", "C" ], and document "D" is currently active. Either of the TouchWrapper components in following example would return to document "A".

{
  "type": "APL",
  "version": "2022.2",
  "extensions": [
    {
      "name": "Backstack",
      "uri": "aplext:backstack:10"
    }
  ],
  "mainTemplate": {
    "item": {
      "type": "Container",
      "items": [
        {
          "type": "TouchWrapper",
          "item": {
            "type": "Text",
            "text": "Go back 3 documents"
          },
          "onPress": {
            "type": "Backstack:GoBack",
            "backType": "count",
            "backValue": 3
          }
        },
        {
          "type": "TouchWrapper",
          "item": {
            "type": "Text",
            "text": "Go to the first document in the backstack"
          },
          "onPress": {
            "type": "Backstack:GoBack",
            "backType": "index",
            "backValue": 0
          }
        }
      ]
    }
  }
}

When the backType is id, a string value is expected for the backValue. If the backstack contains more than one document with the given backValue, the most recent document that matches is the one that is used (i.e., the document with the lowest index).

When the backValue doesn't match an existing element in the backstack array because of an out-of-bounds integer value or a non-existing string, the GoBack command is ignored.

Clear

The Clear command is used to remove all items from the backstack. The Clear command has no additional properties. An example of the Clear command is:

{
  "type": "APL",
  "version": "2022.2",
  "extensions": [
    {
      "name": "Backstack",
      "uri": "aplext:backstack:10"
    }
  ],
  "onMount": {
    "type": "Backstack:Clear",
    "description": "Clear the backstack when this document loads"
  },
  ...
}

Event Handlers

The backstack extension doesn't add any event handlers.

Image filters

The backstack extension doesn't add any new image filters.