Creating a Rich APL Document
Let’s put APL to work by creating an APL template that tells the user to enjoy their trip and includes some basic itinerary details.
APL affords us the opportunity to flex our creative muscles and come up with a visually interesting design. The following APL template employs a mix of Container, Text, and Image components to wish the user an enjoyable trip and show some trip details, all in a outer-space landscape:
| | { "type": "APL", "version": "1.2", "theme": "dark", "mainTemplate": { "items": [ { "type": "Container", "width": "100vw", "height": "100vh", "paddingLeft": "10dp", "paddingTop": "10dp", "paddingRight": "10dp", "paddingBottom": "10dp", "direction": "column", "items": [ { "type": "Image", "width": "100vw", "height": "100vh", "source": "https://starport75.dev/images/planets/stars.jpg", "scale": "fill", "position": "absolute" }, { "type": "Image", "position": "absolute", "bottom": "0", "width": "85vw", "height": "175dp", "source": "https://starport75.dev/images/planets/ earth_cropped.png", "scale": "fill" }, { "type": "Image", "position": "absolute", "bottom": "90dp", "left": "200dp", "width": "300dp", "height": "250dp", "source": "https://starport75.dev/images/planets/ spaceship.png", "scale": "best-fill" }, { "type": "Text", "color": "yellow", "fontSize": "42dp", "text": "Enjoy your trip to Jupiter" }, { "type": "Container", "width": "100vw", "height": "100%", "direction": "row", "items": [ { "type": "Container", "width": "60vw", "height": "100%", "direction": "column", "items": [ { "type": "Text", "color": "lightblue", "fontSize": "24dp", "paddingTop": "12dp", "text": "<b>Departing</b>: 2020-06-09" }, { "type": "Text", "fontSize": "24dp", "color": "lightblue", "paddingTop": "12dp", "text": "<b>Returning</b>: 2020-06-12" } ] }, { "type": "Image", "width": "300dp", "height": "250dp", "source": "https://starport75.dev/images/ planets/Jupiter.png" } ] } ] } ] } } |
The top-level Container component exists primarily to create margins for most of the screen’s contents so that text isn’t bumped up right next to the edge. It’s width and height properties are set to “100vw” and “100vh”, respectively, so that it fills the entire screen. But its paddingTop, paddingBottom, paddingLeft, and paddingRight properties are all set to “10dp” to set the margins.
You’ll also notice that the direction property is set to “column”. This specifies that all of this Container component’s children that are relatively positioned (which is the default) will flow from top to bottom.
That said, the first three children of the Container have their position property set to “absolute”, which frees them from automatic relative positioning and gives us control over the positioning of the components. These Image components establish most of the space scenery that decorates the user-interface and we’ll need to position them in places that relative positioning won’t allow.
The first Image component displays a starfield image that stretches across the entire screen (per the width, height, and scale properties).
The next image represents an Earth landscape that will be spread across the bottom of the screen. The bottom property is set to “0” which, along with absolute positioning, pushes the image to the bottom of the screen (0 pixels from the bottom). The width property is set to “85vw” so that it only stretches across 85% of the screen, leaving a small empty space to its right.
The third image is that of a spaceship that is launching from Earth toward the user’s selected destination. Its positioning and dimensions are a bit more precise to ensure that it appears exactly where we want it relative to the Earth landscape, near the center of the screen.
The remaining children of the top-level Container are relatively positioned, starting with a Text component that is the title of the screen. The Text component is configured to have yellow text and a font size of “40dp” to make it stand out at the top of the screen.
The title Text component is followed by another Container component with direction set to “row”, indicating that its children will flow left-to-right. The left-most child is itself a Container with “column” direction that contains two Text components, one each for the trip’s departure and return dates (hard-coded for now). The right-most child will be an image of the destination planet, currently hard-coded to Jupiter.
To put this template to work, edit the ScheduleTripIntentHandler and add the following before returning the response:
| | if (Alexa.getSupportedInterfaces(handlerInput.requestEnvelope) |
| | ['Alexa.Presentation.APL']) { |
| | const locale = Alexa.getLocale(handlerInput.requestEnvelope); |
| | handlerInput.responseBuilder |
| | .addDirective({ |
| | type : 'Alexa.Presentation.APL.RenderDocument', |
| | document: require('./apl/tripComplete.json') |
| | }); |
| | } |
If APL is supported by the requesting device, then the Alexa.Presentation.APL.RenderDocument directive will be included in the response and the template will be rendered when the user finishes planning a trip. The result will look a little something like this:
That’s an awesome start! But you may have noticed that there are several styling details such as font sizes and colors being set explicitly on the components. Let’s see how to extract those properties into style definitions.