Renderers + Templates

A renderer in the Store is a component that contains all configurations that define how to present an entity in a botlet on a channel. This presentation can be in the form of a card, HTML content, voice, or a combination of these depending on the channel’s capabilities. The renderer component is associated with an entity defined in the Store and has separate configurations for how to present an entity or a list of entities on a specific channel (e.g., Cortana) on a specific canvas (e.g., mobile, voice, or HTML) in that channel. While a renderer needs to be associated with an entity, you can define many renderers for a given entity, each with its own unique renderer ID.

The information that follows will guide you through the steps of adding a renderer to an entity. To do this, we are going to start off by creating a new renderer.

Creating a New Renderer

  1. In the Items Tree, click the Create new icon, and then click New item.
alternate text
  1. Click Renderer, and then click Create new.
alternate text
  1. Enter the Organization name.

Note: To create a renderer, you must have permissions to an organization in the Items tree. For more details about the different types of permissions, see: Permissions.

alternate text
  1. Enter the Renderer Name, Renderer ID, and Entity Type ID in the text fields.
Tip: Type an entity ID in the text field (e.g., car) to select available entity types in the list. You may also select your own entity types in the list if you had previously created them.
  1. Click Done.

Now that a new renderer has been created for an organization, you can now start creating new templates.

Creating a New Template

The information in this section will guide you through the steps of creating a template for a renderer. To demonstrate these steps, we will be selecting Cortana as the channel and chat as one of the canvas types.

You should note that the availability of canvas types is dependent on the channel that you are using for your skill. Cortana can accommodate both chat and voice canvas types. Other channels like Facebook and Telegram use only one canvas type and that is chat.

  1. In the Create a new template wizard, click the Channel drop-down arrow, and then select Cortana.

Note: The Chat Canvas is a generic channel that is used for testing purposes.

alternate text
  1. Click the Canvas drop-down arrow and select Chat, and then click Next.

To decide between using the chat or voice canvas types:

  • You should consider using chat if your skill allows users to type in queries and invocation phrases in digital agents like Cortana and Telegram.
  • You should consider using voice if your skill allows users to talk into smart speakers or other devices that primarily take in voice input commands.
  1. Select Single or List for the card(s).

Notes: A single card and list of cards refers to the template.

  • A template as single is used when one entity object is rendered.
  • A template as list is used when more than one entity object is rendered.
alternate text
  1. Select a Card, and then click Next.

Card Type Options

Selecting single or list in the card settings will also determine which types of cards that are available for your channel. For example, if you select a single card for the Cortana channel, the card type options that you can use for your template are the Action, Audio, and Hero cards.

If you choose a list of cards for the Cortana channel, then the card type options that you can used for your template are the Audio and Hero cards. Other channels like Telegram and Facebook only use Hero cards. If you select a list for these channels, then you can include multiple Hero cards for your channel’s canvas.

For more information and descriptions about each card type option, refer to Defining Renderer Fields.

(Optional) Reusing Existing Templates

It is with this step that you may choose to reuse an existing template for a selected entity type or create a new template.

  1. If you choose to reuse a template, select a template from the list, and then click Copy to renderer.
  2. Otherwise, click Skip and create a new template.
alternate text

It is at this point that you can start Defining Renderer Fields, or you may add new templates to your renderer.

Adding a New Template to a Renderer

If you have a renderer with a template, but you want to add more templates to the renderer, refer to the steps below.

  1. In the Items Tree, click a Renderer.
  2. Click the Templates menu tab, and then click + Add a new template.

Note: From the Overview menu tab, click Edit in templates and this will redirect you to the Templates menu tab.

alternate text
  1. Complete all the steps in the Creating a New Template wizard.

Defining Renderer Fields

To help improve how your skill is searched and displayed in the Store and in channels like Cortana, refer to the steps below for details on defining renderer fields.

  1. In the Items Tree, click a Renderer.
  2. In the Control Panel, click the Templates menu tab.
  3. In the Template name column, click the template name in the list to preview its fields.
alternate text

Note: When you select a template in the list, it will display the card’s field properties in the preview pane. The card fields that can be defined are described below starting with the Action Card.

Action Card

With the Cortana channel selected and chat as the canvas, clicking Single enables you to create an Action card to deep-link applications in Cortana. You can then configure the Launch URI field of the card.

alternate text

An Action Card enables developers to have their skill launch and deep-link an application or website. To launch an application, use the app’s protocol activation URL. In Windows 10, the built-in Maps app supports launching and deep linking into windows apps. For information about the Maps app and the different ways to launch it, see: Launch the Windows Map app.

Launch URI Information

Action Cards utilize Launch URIs. A Launch URI allows skill users to have applications open for them automatically. A Launch URI can start a new e-mail using mailto:. It can open up a web browser using http:. It can open the Windows Maps app using the bingmaps: URI. If a user has Skype installed, they can launch it to start a call or start an instant message conversation. To launch Skype for Business, use the URI “sip:someone@example.com” to open an instant message conversation window. To launch a phone call with Skype for Business, use the URI “tel:123123123123”. If the skill user is signed into the standard version of Skype, use the URI “skype:echo123?call”.

SCL Code Examples to Deep-link Applications

# Open Bing Maps app with Paris as search location
CREATE "$demo.action_entity", action_uri="bingmaps:?where=Paris" STORE ac
RENDER ac, renderer_id="demo.actioncard"
END
# Launch Browser with website
CREATE "$demo.action_entity", action_uri="https://bing.com" STORE ac
RENDER ac, renderer_id="demo.actioncard"
# If the user is signed into Skype for Business,
# the following code opens an instant message conversation window with "someone@example.com".
CREATE "$demo.action_entity", action_uri="sip:someone@example.com" STORE ac
RENDER ac, renderer_id="demo.actioncard"
# If the user is signed into Skype for Business, the following code opens
# a window and readies a phone call to "123123123123".
CREATE "$demo.action_entity", action_uri="tel:123123123123" STORE ac
RENDER ac, renderer_id="demo.actioncard"
# If the user is signed in to the standard version of Skype, the following code
# shows how to start a call with Skype user, echo123.
CREATE "$demo.action_entity", action_uri="skype:echo123?call" STORE ac
RENDER ac, renderer_id="demo.actioncard"
# The following example shows how to create an email in the user's email client
# that's ready for them to send. The example creates and email
# addressed to "someone@example.com", with a subject line of "This is the subject",
# and a body of "This is the body".
CREATE "$demo.action_entity",
action_uri="mailto:someone@example.com?subject=This%20is%20the%20subject&body=This%20is%20the%20body" STORE ac
RENDER ac, renderer_id="demo.actioncard"

Hero Card

With the Cortana channel selected and chat is the canvas, clicking Single or **List enables you to define the fields of the Hero Card.

alternate text

A Hero Card is a multipurpose card. It primarily hosts a single large image, a title, subtitle, button, and “tap action” along with text content that is displayed on the card.

In the Title, Subtitle, and Speak Text fields, you can enter static text, or you can bind to an entity field ${field_name}. The static text that is populated in these fields will get displayed on the skill’s canvas. If you bind to an entity field, then the field properties of that entity will get displayed on the canvas.

Audio Card

With the Cortana channel selected and chat or voice is the canvas, clicking Single enables you to define the fields of the Audio Card.

alternate text

Audio Cards are used for devices such as smart speakers that stream music and e-books. The Media URL is an audio streaming URL. The supported audio formats are MP3, MP4 (i.e., with extensions m4a, aac), and WAV. The Offset field controls the time that the streamed audio gets played. At this time, Audio Cards do not display any information on the channel’s canvas.

Below is sample code for a single Audio card implementation and playlist implementation:

# =================================================================
# Code for single audio implementation
# =================================================================

single_audio:
CREATE "$audio.audio_fields", title="Title of Song", content_url="http://thisisexampleurl/mp3/streaming_audio.mp3" STORE test_audio
RENDER test_audio, renderer_id="audio.audio_card"
END

# =================================================================
# Code for playlist implementation
# =================================================================

playlist:
CREATE "$audio.audio_fields", title="Title of Song 1", content_url="http://thisisexampleurl/mp3/streaming_audio_1.mp3" STORE test_audio_1
CREATE "$audio.audio_fields", title="Title of Song 2", content_url="http://thisisexampleurl/mp3/streaming_audio_2.mp3" STORE test_audio_2
RENDER [test_audio_1, test_audio_2], renderer_id="audio.audio_card"
END

Editing a Template

With the Code Editor feature, you can inspect and edit a template’s HTML, Cascading Style Sheets (CSS)code, and be able to dynamically preview the changes. You also have the option to import your own image by entering the URL path to its location.

Changing Image Size Dimensions

To change the image size, click a Renderer and select the Template menu tab. Click the Edit icon, and change the width and height.

alternate text

Note: Ensure to click Save.

alternate texts

Modifying HTML and CSS

  1. In the Items Tree, click a Renderer.
  2. Click Templates menu tab, and then click the Template name.
  3. With the HTML tab selected, inspect, add, or modify the html code, and then click Reload preview.
alternate text

Note: Repeat these steps, but click the CSS tab to inspect, add, or modifying CSS code.
  1. Click Save.

Using a Static Image

If you want to use your own static image instead of dynamically generating an image in HTML and CSS, refer to the steps below.

Note: The HTML and CSS tabs are disabled when you check the box to enter a URL for a static image. Uncheck this box if you decide to dynamically create your own template image in HTML and CSS.

  1. In the Items Tree, click a Renderer.
  2. In the Control Panel, click Templates.
  3. Click the Templates menu tab, and then click the Template name.
  4. Click Image URL.
alternate text
  1. Check the box to use your own image, and then enter a static image URL or entity ID in the text box.
alternate text
  1. Click Save.

Deleting a Template

The steps below will guide you how to delete a template.

  1. In the Items Tree, select an Renderer.
  2. In the Control Panel, click Templates.
  3. In the template list, click the Template name.
  4. Next, click Delete template.
alternate text
  1. Click Yes to confirm deleting the template.

Deleting a Renderer

The steps below will guide you how to delete a renderer from an organization.

  1. In the Items Tree, select a organization.
  2. Click to expand the Renderers folder, and then select the renderer to be deleted.
  3. Next, click Delete.
alternate text
  1. Click OK to confirm deleting the renderer.
alternate text

Invoking the Renderer in SCL Code

To use a renderer, call the RENDER command in the Semantic Composition Language (SCL) as follows:

RENDER entity, [renderer_id="rendererId"], actions=[action list]

Actions are of type mst.bot.action. You use actions when you want buttons on your rendered cards. Actions work with renderers using the Hero card as well as the ones using the HTML template.

Note: This command will fail causing an error if the command gets executed on a channel that does not have a rendering template configuration.

For more details about calling a service botlet and an action, refer to the SCL command: RENDER.