Viewport Property in the Data-binding Context (APL 1.0)

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. For example, the viewport on an Echo Show has the following properties:

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

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

Properties

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.
`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)

For simplicity, dpi values are simplified to fall into consistent buckets of 120, 160, 240, 320, etc. 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.

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": "2023.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.

Last updated: Oct 07, 2022