Newly Paranoid Maintainers

    @litexa/render-template

    0.8.0 • Public • Published

    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:

    1. concatenate any output speech sent in the next response to the indicated text field
    2. 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 &amp;.

    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:

    Install

    npm i @litexa/render-template

    Homepage

    litexa.com

    DownloadsWeekly Downloads

    3

    Version

    0.8.0

    License

    Apache-2.0

    Unpacked Size

    76.8 kB

    Total Files

    19

    Last publish

    Collaborators

    • alexa-games-admin
    • alexa-games-builder