This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

HTML5

HTML5

Description of HTML5 model supported by Aura

Introduction

Hypertext Markup Language revision 5 (HTML5) is markup language for the structure and presentation of World Wide Web content.

Aura Platform supports HTML5 model, therefore, it is possible to develop experiences that include HTML content in the response.

HTML5 components

There are two main components in the HTML5 model:

  • HTML attachments: set of models whose main property is that the content of the elements to render are composed of HTML5 tags.
  • HTML5 custom tags: different types of custom tags generated to send commands to Aura.

1 - Attachments

HTML5 attachments

Types of HTML attachments for Microsoft Bot Framework

Introduction

HTML attachments are a set of models whose main property is that the content of the elements to render are composed of HTML5 tags.

Aura’s HTML5 attachment template is used to send HTML5 snippets as a response template.

Custom Attachment Model

The custom attachment model contains a free format model.

Bot Framework Attachment Properties

  • Properties marked in bold are mandatory.
  • Properties marked in italics are optional.
Property Type Description
contentType string Content type name.
Value: application/vnd.telefonica.aura.html.custom
content AuraHtmlCustomContent Model of the object where the HTML5 is
version string Attachment model version model
name string Attachment name (optional)

Aura HTML Custom Content

Property Type Description
containers HTMLContainer[] Array of containers where the HTML data is sent

HTML container

The HTML container contains an identifier and the content of HTML.

Content may be self-contained or referenced. If it is self-contained, the property data will contain the HTML. Otherwise, the property url-data will contain the URL to download the HTML.

Property Type Description
id string Identifier of tag where the content data will be placed.
encoded EncodedFormat How the HTML5 code is encoded in data properties. Values: none, base64 or zip
data string HTML5 data.
url-data string URL where the HTML to assign to the given container id should be downloaded. The encoded field in this case is ignored.
content-type string Type of source: html, javascript, css or json.
- If url-data has a URL, the AuraSDK will insert:
. <link href="[url-data]" rel="stylesheet" type="text/css" /> for css.
. <script src="[url-data]"></script> for js.
- If you do not use the Aura SDK, you must insert it manually.
Default value: html
Note: Javascript content cannot be unloaded once loaded into the browser, unless you reload the page or iframe.

Encoded Formats

Property Description
none The data is sent in HTML format
base64 The data is encoded in Base64
zip The data is compressed in zip format

Example

{
  "attachments": [
    {
      "contentType": "application/vnd.telefonica.aura.html.custom",
      "version": "1.0.0",
      "content": {
        "containers": [
          {
            "id": "id-background",
            "url-data":"https://telepizza.com/containers/background?id=334"
          },
          {
            "id": "id-footer",
            "encoded": "base64",
            "data":"PGgyPkhUTUwgTGlua3M8L2gyPgo8cD5IVE1MIGxpbmtzIGFyZSBkZWZpbmVkIHdpdGggdGhlIGEgdGFnOjwvcD4KCjxhIGhyZWY9Imh0dHBzOi8vd3d3Lnczc2Nob29scy5jb20iPlRoaXMgaXMgYSBsaW5rPC9hPg=="
          }
        ]
      }
    }
  ]
}

Building Aura response through HTML5

To include HTML content in Aura’s responses, two conditions must be satisfied:

  • First, generate a response with an attachment whose content has the HTML code.
  • Second, the client must support the model of this type of attachments.

Check how to add attachments into messages in MS Bot Framework.

Generate Response with an HTML5 attachment

In order to generate responses with HTML content, it is necessary to follow the model created for it: Attachment Models.

To do this, simply generate an message attachment with the new model.

For example, if we want to send the word “Hello World” in HTML format:

  1. Generate the necessary HTML code: Hello World! .
  2. Include this code inside the model and assign a container to it, so that the client knows in which part of the webpage he must go. The assignation of a container is mandatory and needs the target Id of HTML element where the content will be rendered.
var message = new Message(session)
    .addAttachment({
        contentType: "application/vnd.telefonica.aura.html.custom",
	  version: "1.0.0"
        content: {
		containers:[
		{
			id: "aura-body",
			data: "<span> Hello World! <span>"
		}
	     ]
	   }
	});

The content can be encoded to avoid problems with HTML code characters or to compress content if it is large. To inform the client of the type of encoding, use the encoded property.

var message = new Message(session)
    .addAttachment({
        contentType: "application/vnd.telefonica.aura.html.custom",
	  version: "1.0.0"
        content: {
		containers:[
		{
			id: "aura-body",
			encoded: "base64",
			data: "PHNwYW4+IEhlbGxvIFdvcmxkISA8c3Bhbj4="
		}
	     ]
	   }
  });

2 - Custom tags

HTML5 custom tags

Custom tags generated to send commands to Aura

Introduction

Discover the different types of custom tags supported by Aura.

Find here general information regarding custom elements.

Aura action tags

The function of this set of tags is to encapsulate all the interactions within the HTML that is sent in the attachment. Any iteration that occurs within the HTML code must generate an event. In this way, the channel only has to manage the events that occur from these tags.

Capabilities:

  • Action tags define the type of event triggered:
    • External as auracommand
    • Internal as internal channel capability
    • etc.
  • Action tags define the trigger to activate the action by voice.
  • Action tags define the targets of HTML elements that is associated to this action by an event.

Aura action: <aura-action>

This tag contains a collection of sub-tags in which the targets, triggers and events necessary to perform this action will be determined.

Property Description
id Optional identifier
name Custom name of the action

Example:

<aura-action name="selectSeat">

</aura-action>

Aura action trigger: <aura-action-trigger> (Not implemented yet)

This tag is used to identify an action based on a voice message from the user.

Initially, are only two types:

  • Regex
  • Proximity

The recognition of the intention of this voice message may be associated with entities.

Property Description
id Optional identifier.
type Recognizer type:
  • Regex: A regular expression engine is executed to determine if the value of reg expression matches with the message of voice. This expression may contain groups to identify entities.
  • Proximity: This type uses a proximity phrase comparison algorithm. Based on a minimum resemblance value (min-threshold), it will determine if the event will be triggered. You can include entities in the entity field.
value Text to compare. If the type is Regex, this text must be a regular expression.
entity It represents one o more entities to send to the event if the trigger is activated.
entity-field In the case of a regular expression, it represents an entity calculated on the basis of the regular expression.

Examples:

    <aura-action-trigger type="regex" value="/select seat ([1-500])/" entity-field="$1">  </aura-action-trigger>
    <aura-action-trigger type="proximity" min-threshold="0.99" value="select seat 1C" entity="32">  </aura-action-trigger>

Aura action target: <aura-action-target>

It defines the targets of HTML elements that are associated to this action by an HTML event.

Property Description
id Optional identifier.
target Pattern to determine the identifiers of the tags from the elements that compose the HTML. The format of the pattern is a querySelector syntax.
event HTML event to which the action should be associated. For example: click
evalue JSON Object to validate. The JSON object has the properties field and value. The evaluation returns true if the field contains the value.
Example: {"field":"checked", "value":true}
mode Modality of target element: submit, single or multiple.
  • submit: this value indicates that the composition of the aura-event will be done after the event is launched.
  • single: this value indicates that you only need to evaluate one element independently.
  • multiple: this value indicates that the final composition depends on a set of elements.
entity-field It represents a property in the target element to be used as entity.
voice-field It represents a property in the target element to be used for dialogContext models. This value can contain multiple string fields separated by pipes (\, `
canon-field It represents a property in the target element to be used as canon.
entity-type It represents the type property of the entity model
entity-default Used to set a entity by default when the command is build.
canon-default Used to set a canon by default when the command is built.
voice-default Used as an alternative for voice-field.

Aura action event: <aura-action-event>

It contains the event that will be generated if the action is activated. This event is associated with a data model that contains the information related to the event.

Property Description
id Optional identifier. Optional
type Type of event generated if the action is launched. Values: auraCommand.
intent Intent of the command.
command-type Type of auraCommand. Values: intent, operation or text.
event-hook Event to hook the result of the event. It is used to add an event listener to capture the event and result of an aura-action-event.
Example: aura-la-event.
Example of capture: document.body.addEventListener("aura-la-event", customFunction, true).

Examples

To capture the events:

<script>
  /** To capture the event
  /* 1.- Add the listener
  **/
  document.body.addEventListener("seatSelected", customFunction, true);
  /* 2.- create the function to execute */
  function customFunction(e) {
    console.log(e.detail);
}
</script>

Single Button

<input type="button" id="b-1" data-seat="1A" value="Seat 1A" />
<input type="button" id="b-2" data-seat="1B" value="Seat 1B" />
<input type="button" id="b-3" data-seat="1C" value="Seat 1C" />
<input type="button" id="b-4" data-seat="1E" value="Seat 1E" />
<input type="button" id="b-5" data-seat="1F" value="Seat 1F" />
<!--Aura custom tags-->
<aura-action id="selectSingleButton">
   <aura-action-target target="[id^=b-]" event="click" entity-field="value" canon-field="data-seat" entity-type="seat" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

Result if button with id=b-1 was clicked:

{
    "auraCommand": {
        "type": "operation",
        "value": {
            "intent": "operation.select.seat",
            "entities": [
                {
                    "entity": "1A",
                    "type": "seat",
                    "canon": "Seat 1A"
                }
            ]
        }
    }
}

Multiple button

<input type="button" id="bm-1" data-seat="1A" value="Seat 1A" class="unselected" onclick="switchStyle(this)" />
<input type="button" id="bm-2" data-seat="1B" value="Seat 1B" class="unselected" onclick="switchStyle(this)" />
<input type="button" id="bm-3" data-seat="1C" value="Seat 1C" class="unselected" onclick="switchStyle(this)" />
<input type="button" id="bm-4" data-seat="1D" value="Seat 1D" class="unselected" onclick="switchStyle(this)" />
<input type="button" id="bm-5" data-seat="1E" value="Seat 1E" class="unselected" onclick="switchStyle(this)" /> <br /> <br />
<input type="button" id="sbm" data-seat="send" value="Submit" />
<!--Aura tags-->
<aura-action id="selectMultipleButton">
   <aura-action-target target="[id^=bm-]" event="click" entity-field="value" canon-field="data-seat" entity-type="seat" mode='multiple'> </aura-action-target>
   <aura-action-target target="[id^=sbm]" event="click" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

Radio Button

<input type="radio" name="rbseat" data-seat="1A" value="Seat 1A" />Seat 1A <br />
<input type="radio" name="rbseat" data-seat="1B" value="Seat 1B" />Seat 1B <br />
<input type="radio" name="rbseat" data-seat="1C" value="Seat 1C" />Seat 1C <br />
<input type="radio" name="rbseat" data-seat="1D" value="Seat 1D" />Seat 1D <br />
<input type="radio" name="rbseat" data-seat="1E" value="Seat 1E" />Seat 1E <br /> <br />
<input type="button" id="srbseat" data-seat="send" value="Submit" />
<!--Aura tags-->
<aura-action id="selectSimpleRadio">
   <aura-action-target target="[name^=rbseat]"  entity-field="value" canon-field="data-seat" entity-type="seat" mode='single'  evalue='{"field":"checked", "value":true}'> </aura-action-target>
   <aura-action-target target="[id^=srbseat]" event="click" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

Checkbox Button

<input type="checkbox" name="chkseat" data-seat="1A" value="Seat 1A" />Seat 1A <br />
<input type="checkbox" name="chkseat"  data-seat="1B" value="Seat 1B" />Seat 1B <br />
<input type="checkbox" name="chkseat" data-seat="1C" value="Seat 1C" />Seat 1C <br />
<input type="checkbox" name="chkseat" data-seat="1D" value="Seat 1D" />Seat 1D <br />
<input type="checkbox" name="chkseat" data-seat="1E" value="Seat 1E" />Seat 1E <br /> <br />
<input type="button" id="schkseat" data-seat="send" value="Submit" />
<!--Aura tags-->
<aura-action id="selectByCheckboxMultiple">
   <aura-action-target target="[name^=chkseat]" event="click" entity-field="value" canon-field="data-seat" entity-type="seat" mode='multiple'> </aura-action-target>
   <aura-action-target target="[id^=schkseat]" event="click" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

Result if the first and the last checkboxes were checked:


{
    "auraCommand": {
        "type": "operation",
        "value": {
            "intent": "operation.select.seat",
            "entities": [
                {
                    "entity": "1A",
                    "type": "seat",
                    "canon": "Seat 1A"
                },
                {
                    "entity": "1E",
                    "type": "seat",
                    "canon": "Seat 1E"
                }
            ]
        }
    }
}

Select Single

<select name="selectOpt">
   <option id="op-1" label="Seat 1A" value="1A">Seat 1A</option>
   <option id="op-2" label="Seat 1B" value="1B">Seat 1B</option>
   <option id="op-3" label="Seat 1C" value="1C">Seat 1C</option>
   <option id="op-4" label="Seat 1D" value="1D">Seat 1D</option>
   <option id="op-5" label="Seat 1E" value="1E">Seat 1E</option>
</select>
<!--Aura tags-->
<aura-action id="selectSingleOption">
   <aura-action-target target="[id^=op-]" evalue='{"field":"selected", "value":true}' entity-field="label" canon-field="value" entity-type="seat" mode='single' > </aura-action-target>
   <aura-action-target target="[name^=selectOpt]" event="change" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

Select Multiple

<select name="selectOpt">
   <option id="op-1" label="Seat 1A" value="1A">Seat 1A</option>
   <option id="op-2" label="Seat 1B" value="1B">Seat 1B</option>
   <option id="op-3" label="Seat 1C" value="1C">Seat 1C</option>
   <option id="op-4" label="Seat 1D" value="1D">Seat 1D</option>
   <option id="op-5" label="Seat 1E" value="1E">Seat 1E</option>
</select>
 <input type="button" id="smop" data-seat="send" value="Submit" />
<!--Aura tags-->
<aura-action id="selectMultipleOption">
   <aura-action-target target="[id^=mop-]" evalue='{"field":"selected", "value":true}' entity-field="label" canon-field="value" entity-type="seat" mode='multiple' > </aura-action-target>
   <aura-action-target target="[id^=smop]" event="click" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

Input Text

<input type="text" id="textSelect" />
<input type="button" id="textType" data-seat="send" value="Submit" />
<!--Aura tags-->
<aura-action id="selectText">
   <aura-action-target target="[id^=textSelect]" entity-field="value" canon-field="value" evalue="" entity-type="seat" mode='single'> </aura-action-target>
   <aura-action-target target="[id^=textType]" event="click" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

All In One

<body>
   <section>
      <input type="button" id="bm-1" data-seat="1A" value="Seat 1A" class="unselected" onclick="switchStyle(this)" />
      <input type="button" id="bm-2" data-seat="1B" value="Seat 1B" class="unselected" onclick="switchStyle(this)" />
      <input type="button" id="bm-3" data-seat="1C" value="Seat 1C" class="unselected" onclick="switchStyle(this)" />
      <input type="button" id="bm-4" data-seat="1D" value="Seat 1D" class="unselected" onclick="switchStyle(this)" />
      <input type="button" id="bm-5" data-seat="1E" value="Seat 1E" class="unselected" onclick="switchStyle(this)" />     
   </section>
   <section>
      <input type="radio" name="rbseat" data-seat="1A" value="Seat 1A" />Seat 1A <br />
      <input type="radio" name="rbseat" data-seat="1B" value="Seat 1B" />Seat 1B <br />
      <input type="radio" name="rbseat" data-seat="1C" value="Seat 1C" />Seat 1C <br />
      <input type="radio" name="rbseat" data-seat="1D" value="Seat 1D" />Seat 1D <br />
      <input type="radio" name="rbseat" data-seat="1E" value="Seat 1E" />Seat 1E <br />
   </section>
   <section>
      <input type="checkbox" name="chkseat" data-seat="1A" value="Seat 1A" />Seat 1A <br />
      <input type="checkbox" name="chkseat" data-seat="1B" value="Seat 1B" />Seat 1B <br />
      <input type="checkbox" name="chkseat" data-seat="1C" value="Seat 1C" />Seat 1C <br />
      <input type="checkbox" name="chkseat" data-seat="1D" value="Seat 1D" />Seat 1D <br />
      <input type="checkbox" name="chkseat" data-seat="1E" value="Seat 1E" />Seat 1E <br /> 
   </section>
   <section>
      <select name="selectOpt">
         <option value=""></option>
         <option id="op-1" label="Seat 1A" value="1A">Seat 1A</option>
         <option id="op-2" label="Seat 1B" value="1B">Seat 1B</option>
         <option id="op-3" label="Seat 1C" value="1C">Seat 1C</option>
         <option id="op-4" label="Seat 1D" value="1D">Seat 1D</option>
         <option id="op-5" label="Seat 1E" value="1E">Seat 1E</option>
      </select>
   </section>
   <section>
      <select name="mselectOpt" multiple>
         <option id="mop-1" label="Seat 1A" value="1A">Seat 1A</option>
         <option id="mop-2" label="Seat 1B" value="1B">Seat 1B</option>
         <option id="mop-3" label="Seat 1C" value="1C">Seat 1C</option>
         <option id="mop-4" label="Seat 1D" value="1D">Seat 1D</option>
         <option id="mop-5" label="Seat 1E" value="1E">Seat 1E</option>
      </select>
      <br />
   </section>
   <section>
      <input type="text" id="textSelect" /> 
      <input type="button" id="textType" data-seat="send" value="Submit" />
   </section>
   <!--Aura tags-->
   <aura-action id="selectSeat">
      <aura-action-target target="[id^=bm-]" event="click" entity-field="data-seat" canon-field="value" entity-type="seat2" mode='multiple'> </aura-action-target>
      <aura-action-target target="[name^=rbseat]" entity-field="value" canon-field="data-seat" entity-type="seat3" mode='single' evalue='{"field":"checked", "value":true}'> </aura-action-target>
      <aura-action-target target="[name^=chkseat]" event="click" entity-field="value" canon-field="data-seat" entity-type="seat4" mode='multiple'> </aura-action-target>
      <aura-action-target target="[id^=op-]" evalue='{"field":"selected", "value":true}' entity-field="label" canon-field="value" entity-type="seat5" mode='single'> </aura-action-target>
      <aura-action-target target="[id^=mop-]" evalue='{"field":"selected", "value":true}' entity-field="label" canon-field="value" entity-type="seat6" mode='multiple'> </aura-action-target>
      <aura-action-target target="[id^=textSelect]" entity-field="value" evalue="" canon-field="value" entity-type="seat7" mode='single'> </aura-action-target>
      <aura-action-target target="[id^=textType]" event="click"  mode='submit'> </aura-action-target>
      <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
   </aura-action>
</body>