Viewport Object in the Data-binding Context (APL 1.1 to 2023.2)

Note: Learn how to improve your skills with APL with Build visually rich experiences using APL at the Alexa Learning Lab.

(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)

The data-binding context includes a viewport property that describes the operating characteristics of the display device.

Note: The viewport property is available to your APL document as part of the data-binding context. This is separate from the viewport information included in requests sent to your skill, which you can access in your skill code.

Viewport property example

For example, the viewport on the original Echo Show reports the following properties:

{
  "viewport": {
    "width": 1024,
    "height": 600,
    "pixelWidth": 1024,
    "pixelHeight": 600,
    "shape": "rectangle",
    "dpi": 160,
    "theme": "dark",
    "mode": "hub"
  }
}

Your skill can use conditional logic to provide different responses for different viewports.

Viewport property example
Properties
- dpi
- Shape
- Height and width
- mode
- Pixel height and width
- Theme

Properties

The following properties are defined in the viewport property.

Property	Type/Values	Description
`dpi`	Integer	Pixel density of the viewport.
`height`	Integer	Height of the viewport in dp.
`mode`	Mode	The operating mode
`pixelHeight`	Integer	Height of the viewport in pixels.
`pixelWidth`	Integer	Width of the viewport in pixels.
`shape`	`round` or `rectangle`	Shape of the viewport.
`width`	Integer	Width of the viewport in dp.
`theme`	`light` or `dark`	The preferred color scheme

dpi

The display-independent pixel (dp) measurement of a screen is an artificial value that represents the visual size of the screen assuming that the screen is held at a mobile-phone viewing distance and has a pixel density of approximately 160 pixels per inch (the original iPhone screen was 163 pixels per inch). Two screens viewed at the same distance with the same physical size have approximately the same dp dimensions regardless of the actual pixel density of the screen.

The dots-per-inch (dpi) of a viewport is an artificial value that reflects the visual size of a point or pixel relative to the observer, and it does not match the actual pixels-per-inch size of the screen. The formula for dpi is:

dpi = 160 * (pixelSize / dpSize)

The following DPI values are supported: 120, 160, 213, 240, 320, 480,

In practice the manufacturer selects the dpi size of the screen based on physical dimensions and expected viewing distance, then calculates the dpSize based on that dpi. For example, manufacturers recommend a 1080p television watching distance of approximately twice the diagonal measurement of the television screen, regardless of the actual screen size. Because the apparent visual size of the TV to the viewer is constant, all 1080p televisions have dpi=320, with pixelHeight of 1080 and height of 540.

Shape

The shape of the screen is set to either round or rectangle.

Height and width

The height and width properties are set to the current display-independent pixel measurements of the screen. You should not assume that these are fixed values for a particular device. The height and width reflect the current orientation of a screen. Tablet computers that rotate between landscape and portrait mode report the width and height of the screen appropriate for the mode they are in. For example, a 1024x600 dp tablet will report a width of 1024 in landscape mode and of 600 in portrait mode.

mode

The mode property describes the expected use of the device. The mode property is assigned one of the following values:

Value	Description	Common input types	Examples
`auto`	Used by the driver in a vehicle	Touch	Automobile dashboard, built-in aircraft display
`hub`	A table-top or fixed-position devices	Touch (when close)	Amazon Echo Show, counter-top appliance
`mobile`	A handheld device carried by the user	Touch	Mobile phone, tablet computer
`pc`	A desktop or laptop computer	Keyboard, mouse, trackpad	Desktop, laptop computer
`tv`	A television or projected display	Remote control	Television, billboard

The input types listed in the table above are representative and not guaranteed to exist for a particular device mode.

A single device may report different modes at different times. For example, a tablet computer reports as a "mobile" device at most times, but might report as a "hub" device when it is docked in a docking station. Proximate devices often report as different modes. For example, in an automobile the device built into the dashboard would report as "auto", the device installed in the ceiling behind the driver for passengers would report as "tv", and the mobile phone held by a passenger would report as "mobile".

The list of modes might change. When you use mode in conditional logic, assume that the property could return an unrecognized value. Always provide a default definition for any properties or components that depend upon mode.

Pixel height and width

The pixelHeight and pixelWidth properties are set to the current pixel measurements of the screen. The pixelHeight and pixelWidth reflect the current orientation of a screen. Tablet computers that rotate between landscape and portrait mode report the pixelHeight and pixelWidth of the screen appropriate for the mode they are in. For example, a 1024x600 dp tablet will report pixelWidth of 1024 in landscape mode and 600 in portrait mode.

Theme

The theme reflects the basic color scheme in use on the device. The theme is a string value. You can set the theme in the APL document in the theme property. If it is not set in the document, the device sets it to either "light" or "dark":

light: Dark text drawn on a light background
dark: Light text drawn on a dark background

You can use the theme when you define styles in your document or package. For example::

{
  "styles": {
    "styledText": {
      "values": [
        {
          "color": "${viewport.theme == 'dark' ? 'white' : 'black'}"
        }
      ]
    },
    "styledFrame": {
      "values": [
        {
          "backgroundColor": "${viewport.theme == 'dark' ? '#096484' : '#74B6CF'}"
        }
      ]
    }
  }
}

In your document, you can choose to ignore the theme entirely or override the device-supplied value with a custom them. For example, this document creates a custom "fancy" theme:

{
  "type": "APL",
  "version": "2024.1",
  "theme": "fancy",
  "styles": {
    "styledText": {
      "description": "A text style that selects colors based on the light, dark, and fancy themes",
      "values": [
        {
          "color": "white"
        },
        {
          "when": "${viewport.theme == 'light'}",
          "color": "black"
        },
        {
          "when": "${viewport.theme == 'fancy'}",
          "color": "red"
        }
      ]
    }
  },
  "mainTemplate": {
    "items": {
      "type": "Text",
      "style": "styledText"
    }
  }
}

This approach provides flexibility when the styles and resources are moved to an imported APL package. Then the document author can easily switch between various custom appearances with a single theme choice.

Was this page helpful?

Provide feedback

Last updated: Nov 28, 2023