What's New in APL 1.8

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

Alexa Presentation Language (APL) 1.8 introduces new features and capabilities for APL.

Viewport profiles package

New viewport profiles

The alexa-viewport-profiles package includes the following two new profiles to support the Echo Show 15:

  • Hub Landscape Extra Large (@hubLandscapeXLarge)
  • Hub Portrait Medium (@hubPortraitMedium)

Use these profiles when building your conditional logic to make sure that your content looks good on all Alexa devices. Select these new profiles in the authoring tool and simulator to preview your content on this device.

The following table summarizes the two new profiles.

Viewport profile Shape / Orientation Mode minWidth / maxWidth minHeight / maxHeight

hubLandscapeXLarge

rectangle / landscape

hub

1920 – 2560

960 – 1279

hubPortraitMedium

rectangle / portrait

hub

960 – 1279

1920 – 2560

For more about the viewport profiles available in alexa-viewport-profiles, see Viewport Profiles.

For details about how to preview your content with different viewports in the authoring tool, see Preview an APL Document.

For details about how to test your skill with different viewports in the simulator, see Test APL Skills in the Developer Console Simulator.

The responsive components and templates in the alexa-layouts package support the two new viewport profiles. For details about how to use the responsive components and templates, see Responsive Components and Templates.

After you have updated your skill to support the new viewport profiles, update the list of profiles that your skill supports. You can make this update on the Interfaces page in the developer console or using the ASK CLI. For details, see Select the Viewport Profiles Your Skill Supports.

Other updates to the viewport profiles package

The @viewportSizeClass resource in the package now includes an additional possible value: @viewportClassMediumXLarge. For more about resources about how to determine the viewport size, see Size Classes.

Import the Alexa packages into your APL document

To use the latest components, templates, styles, and resources, update your APL document to import the latest versions of the packages.

Package Version

alexa-layouts

1.4.0

alexa-styles

1.3.0

alexa-viewport-profiles

1.3.0

For an overview of the components and templates, see Responsive Components and Templates.

Improved image and video handling

The Image, VectorGraphic, and Video components now include handlers that run when the items load or fail to load. For example, if an image fails to load because the URL is invalid, the component invokes the new onFail handler. Configure these handlers with commands to handle this situation. For example, if an image fails to load, you might run SetValue to change source to a different placeholder image.

See the following new handlers:

Override environment defaults

The environment object in the data-binding context contains runtime information about the operating APL environment. You can now override certain properties to change document-level defaults.

To override these defaults, you set properties in the document-level environment object. You can override the following two properties:

  • lang – The default language (BCP-47 format) used for text display.
  • layoutDirection – The default component and text layout direction for the document`

This change simplifies supporting right-to-left languages such as Arabic, as well as supporting language-specific fonts. Previously, you had to use the component-level layoutDirection and lang properties, which meant that you might need to set these values on multiple components in your document. Now, you can set these values one time, at the document level, and they apply throughout your layout. You can also use these document defaults when building resources for use in your document.

Use data-binding to set the environment.layoutDirection and environment.lang properties to values in your data source. When your skill constructs the data source to send with the RenderDocument directive, set these properties in the data source based on the locale provided in the request. This method lets you use the same APL document for both left-to-right and right-to-left content.

For details about how you set the document-level environment property, see the document environment property.

For an example that shows using the document-level environment property with responsive components and templates, see Support for Right-to-left Languages in the Responsive Components and Templates.

General updates

Data-binding context

  • The environment property in the data-binding context now gives you access to the document-level layoutDirection and lang properties. Access the current document-level settings for these properties with ${environment.layoutDirection} and ${environment.lang}. These properties can be useful when building language-appropriate resources. For details, see the environment object in the data-binding context.
  • New displayState property in the initial data-binding context to report whether the document is hidden, in the foreground, or in the background. For details, see displayState.

Document properties

  • New environment property at the document level. Use this property to override environment settings. You can override layoutDirection and lang properties. For details, see the document environment property.
  • New onDisplayStateChange handler to define commands that run when the document displayState changes. For details, see the onDisplayStateChange property.

Component properties

Work with APL versions

For details about how to check the APL version, see What's New in APL.

Was this page helpful?

Last updated: Jun 18, 2024