Litexa Render Template

Alexa's Display interface allows for showing static, one-size-fits-all screens on compatible Alexa-enabled screen devices. This is achieved by sending render templates in a Display.RenderTemplate directive (see Display Interface Reference for more details).

The @litexa/render-template module adds support for easily building, sending and validating such Display.RenderTemplate directives from within Litexa.

Installation

The module can be installed globally, which makes it available to any of your Litexa projects:

npm install -g @litexa/render-template

If you alternatively prefer installing the extension locally inside your Litexa project, for the sake of tracking the dependency, just run the following inside of your Litexa project directory:

npm install --save @litexa/render-template

This should result in the following directory structure:

project_dir
├── litexa
└── node_modules
    └── @litexa
        └── render-template

New Statement

When installed, the module adds a new screen statement to Litexa's syntax, which can be used to send a specific render template type via directive as follows:

screen
  template: "BodyTemplate1"

The supported template types are split into two categories:

1) Body Templates

The following body templates are supported along with their respective attributes:

template type	`background`	`title`	`primaryText`	`secondaryText`	`tertiaryText`	`displaySpeechAs`	`image`	`hint`
BodyTemplate1	✓	✓	✓	✓	✓	✓
BodyTemplate2	✓	✓	✓	✓	✓	✓	✓	✓
BodyTemplate3	✓	✓	✓	✓	✓	✓	✓
BodyTemplate6	✓	✓	✓	✓	✓	✓		✓
BodyTemplate7	✓	✓				✓	✓

Example: BodyTemplate2

Here's an example of sending a BodyTemplate2 with every possible attribute (any subset of attributes is allowed).

screen
    template: BodyTemplate2
    title: "Cheese Varieties"
    primaryText: "Brie originated in France"
    secondaryText: "Gruyere originated in Switzerland"
    tertiaryText: "Gorgonzola originated in Italy"
    background: background.jpg
    image: "https://www.example.com/my-image.png"
    displaySpeechAs: "title"
    hint: "Cheesy Hint"

The displaySpeechAs attribute requires a value that is:

one of [title, primaryText, secondaryText, tertiaryText]
supported by the specified template type

Setting this attribute will:

concatenate any output speech sent in the next response to the indicated text field
strip any SSML tags (e.g. <say-as interpret-as='ordinal'>) from the displayed text

2) List Templates

The following list templates are supported along with their respective attributes:

template type	`background`	`title`	`list`
ListTemplate1	✓	✓	✓
ListTemplate2	✓	✓	✓

The list attribute requires an array of list items. Each list item is an object with any subset of the attributes: [token, primaryText, secondaryText, tertiaryText, image]

The token attribute is optional and list item-specific. It sets an author-chosen String identifier for the associated list item. For example:

// list litem:
{
  token: 'My List Item Token',
  primaryText: 'My list item'
}

The token can then be used to identify which list item was touched - see the following example.

Example: ListTemplate1

Here's an example of sending a ListTemplate1 with every attribute, and handling touch events.

Dynamically generating the list in some JS code:

// static list
let list = [
    {token: 'brie', primaryText: 'Brie (France)', image: 'brie.jpg'},
    {token: 'gruyere', tertiaryText: 'Gruyere (Switzerland)', image: 'gruyere.jpg'},
];

// alternative or supplementary code to assemble/manipulate a dynamic list
let listItem = {token: 'gorgonzola', secondaryText: 'Gorgonzola (Italy)', image: 'gorgonzola.jpg'};
list.push(listItem);
// (...)

const getList = function() {
    return list;
}

Sending the list directive in litexa:

local myCheeseList = getList()
screen
    template: ListTemplate1
    background: background.jpg
    title: "Cheese List"
    list: myCheeseList

when Display.ElementSelected
    say "You touched list item {$request.token}."

The above example would display the defined list on the screen and, if an item were touched by the user, Alexa would say the item's token out loud. The touch event and corresponding token can be handled in whichever way is required.

Statement Shorthands

There are several statement shorthand options available.

screen [title] [background]  # screen "My Title" background.jpg
screen [background] [title]  # screen background.jpg "My Title"
screen [title]               # screen "My Title"
screen [background]          # screen background.jpg

Statement Attribute Specifications

Attribute properties

If no template is specified, the template type defaults to BodyTemplate1.
hint will generate a Hint Directive with the supplied String, and add it to the pending response.
image and background expect one of the following:
- Unquoted or quoted name of a file provided in litexa/assets.
- Existing image's URL as a String (litexa does not validate URL's existence).
- A variable storing either of the above.
image and primary|secondary|tertiaryText size and placement depend on which template is used (see examples in Display Template Reference).

TIP: It is useful to frequently test your skill on an Alexa device or the ASK Developer Console (ideally test each device type), to detect any unforeseen rendering issues (e.g. text overflow).

Attribute shorthands

As can be seen in the above examples, we've shortened some of the official render template attributes (see Display Template Reference), for the sake of convenience:

Use background instead of backgroundImage.
Use list instead of listItems.
Directly use primary|secondary|tertiaryText instead of a textContent container.

Text Formatting

The text attributes primary|secondary|tertiaryText support the below RichText HTML tags.

NOTE: These HTML tags are supported without requiring closing tags - see the examples below.

Bold, Italics, Underlined

"<b a bold sentence 1>"
"<b> a bold sentence 2"
"<b> bold
  not bold"

For italics and underlined, use <i> and <u> analogously.

Font Sizes

"<f2 this has font size two> <f3 this has font size three>"
"<f3> font size three"
"regular size <f5 size 5>"
"<f7 size 7> regular size"

Only the following font sizes are allowed: [2,3,5,7]

Alignment

"<center something 1>"
"<center>something 2"
"<center> centered
  not centered"
"<center> centered
  <center> also centered"

Mixing Tags

"<center><u><b>centered, underlined and bold"
"<center><b>centered and bold
  neither
  <b><f7 bold and large><f2 bold and small>"

Special Characters

You should only use the special characters newline (\n) and ampersand (&) in primary|secondary|tertiaryText. These two characters will automatically be converted to the HTML tags <br/> and &.

Intent Handling Requirements

When using a Render Template directive, certain built-in intents must be supported by the skill (i.e. included in at least one when listener). Not doing so will result in an error during deployment.

The following intents should be handled correctly by the skill author, to control the skill's screen flow:

AMAZON.NextIntent
AMAZON.PreviousIntent

The following intents must also be included, but can be routed to do nothing since they have automatic handling:

AMAZON.ScrollUpIntent
AMAZON.ScrollDownIntent
AMAZON.ScrollLeftIntent
AMAZON.ScrollRightIntent
AMAZON.MoreIntent
AMAZON.NavigateHomeIntent
AMAZON.NavigateSettingsIntent
AMAZON.PageDownIntent
AMAZON.PageUpIntent

Examples of the above mentioned automatic handling are:

ListTemplate1 will automatically "scroll down" and "scroll up"
ListTemplate2 will automatically "scroll right" and "scroll left"

If no custom handling is required, the intent listeners can be added to an unreachable state:

invalidIntents # nothing points to this state
  when AMAZON.ScrollUpIntent
    # do nothing

Doing so would include the intents in the skill model, while not ever actively handling them.

Checking Render Template Support

To check whether the Display interface, and therewith render templates are supported by the active device at runtime, the following command can be used in litexa or external code:

RenderTemplate.isEnabled()

This check can and should be used to potentially compensate for any missing visuals on a voice-only device. For example:

  if RenderTemplate.isEnabled()
    screen instructions.png
    say "Please read the instructions on the screen."
  else
    say "Here are your instructions: @instructions"

Resources

For more information, please refer to the official Display Render Templates documentation: