Aura –

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

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:

Generate the necessary HTML code: Hello World! .
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="
		}
	     ]
	   }
  });

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

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>