VOGO Voice – Knowledge Base

Template Engine

Estimated reading time: 4 min

The purpose of the template engine is to allow more complex expressions, logic, and dynamic content to be generated in order to create any type of custom skill. We make use of the Handlebars Engine with a few added features that allow us to run more complex functions. This article should encompass all that is needed we do encourage you to read more on Handlebars if you are curious about how the engine works.

Syntax & Data

When wanting to reference any data within a response card or many other components that support templates it is simply adding double open {{ and closing }} curly brackets to the text. Let us say I created an intent and interaction that looked something like “My favorite color is {myColor}”. If this was my intent I set up then I know that if I wanted to repeat that in my “Response Card” component in an interaction I could reference it by typing I also like the color {{inputs.myColor.value}}. and this would replace the {{ section }} with the color spoken to be I also like the color blue. We have a wide variety of data that can be referenced and suggest reading up on our Data Breakdown Guide for all of the different values.

Simple If/else

The next most common situation is when the response may be depending on a value or the display on the screen needs to say something if the value is one or another. In these cases an If/else if most common and can be used as shown.

Data:
{
  isActive: true
}

Template:
{{#if isActive}}
  It is active.
{{else}}
  It is not active.
{{/if}}

There are cases when you will want to have an if/elseIf/else logic and can be done in the manner below.

Data:
{
  isActive: true,
  isEnabled: true,
}

Template:
{{#if isActive}}
  It is active.
{{else if isEnabled}}
  It is enabled but not active.
{{else}}
  It is not active nor enabled.
{{/if}}

Advanced If/else

For more advanced used cases where you need to test something beyond a simple exists or boolean expression we also support all the normal conditional logic. Use any of the values in the list as shown in the examples.
Compare types are:

OperatorReason
!=Does not equal (Not Strict Comparison)
!==Does not equal (Strict Comparison)
<Less than
<=Lean than or equal to
==Equals (Not Strict Comparison)
=== or = (shorthand)Equals (Strict Comparison)
>Greater than
>=Greater than or equal to
noneOf The right argument is not included in the left. Typically used for value in an array.
Reference
oneOf The right argument is included in the left. Typically used for value in an array.
Reference
typeof Compares if the left and right types are the same.
{{#if key operator value}}

Data:
{
  count: 1
}

Examples:
{{#if count '===' 0 }}
{{#if count '===' 1 }}
{{#if count '>' 1 }}

Evaluation Context

each and with let you switch context to simplify your temple. Given the below example you can reference inner keys by simply change the context.

Data:
{
  person: {
    firstname: "Yehuda",
    lastname: "Katz"
  }
}

Tempalte:
{{#with person}}
{{firstname}} {{lastname}}
{{/with}}

When using the each syntax {{this}} represents the value of the array context it is looping over.

Data:
{
  people: [
    "Yehuda Katz",
    "Alan Johnson",
    "Charles Jolley"
  ]
}

Template:
{{#each people}}
  {{this}}
{{/each}}

If the array is of objects then you would want to adjust the syntax slightly. See the following example.

Data:
{
  people: [
    { "first": "Yehuda", "last": "Katz" },
    { "first": "Alan", "last": "Johnson" },
    { "first": "Charles", "last": "Jolley" }
  ]
}

Template:
{{#each people}}
  {{first}} {{last}}
{{/each}}

Random Value

There are cases where we would like to randomly pick a value from a list of various results. We can do this with the following syntax.

{{random Array}}

Data:
{ 
  welcomeList: ["Welcome", "Hi", "Good day"]
}

Examples:
{{random welcomeList}}

Parsing String into JSON (jsonParse)

There are cases where the text of a previous result was not an object but a string representing JSON. There are other cases when you want to create your own Array or JSON object. In both cases, you can use the jsonParse to easily access this information. Below are a few examples.

Context Example:
{{#with (jsonParse '{"text":"Success"}') }}
{{text}}
{{/with}}

Results:
Succcess

Loop Example:
{{#each (jsonParse '[{"text":"Success 1"}, {"text":"Success 2"}]') }}
{{text}}
{{/each}}

Results:
Success 1 Success 2

Show List Example:
{{#showList (jsonParse '[{"text":"Success 1"}, {"text":"Success 2"}]') }}
{{text}}
{{/showList}}

Results:
Success 1 and Success 2

Random Result from Array
{{random (jsonParse '["Success 1", "Success 2"]') }}

Results: Can be either value randomly

Random Result from Object
{{#with (random (jsonParse '[{"text":"Success 1"}, {"text":"Success 2"}]')) }}
{{text}}
{{/with}}

Results: Can be either value randomly

Showing Lists

There are cases where you will want to create a list like A, B, and C or A, B, or C or A|B|C. In all of these cases, it can be tricky to create this expression and this is where the showList function comes in handy. Follow the examples below for creating various lists.

Basic Syntax: {{#showList Array}}{{this}}{{/showList}}
Basic Syntax: {{#showList Array}}{{field1}} {{field2}}{{/showList}}
Advanced Syntax: {{#showList Array Options}}{{this}}{{/showList}}
Advanced Syntax: {{#showList Array Options}}{{field1}} {{field2}}{{/showList}}

Data:
{
  list: ["A", "B", "C"]
  people: [
    { "first": "Yehuda", "last": "Katz" },
    { "first": "Alan", "last": "Johnson" },
    { "first": "Charles", "last": "Jolley" }
  ]
}

Template:
{{#showList list}}{{this}}{{/showList}}
{{#showList list lastWord="or"}}{{this}}{{/showList}}
{{#showList list lastWord="" join="; "}}{{this}}{{/showList}}
{{#showList list lastWord="" join="|"}}{{this}}{{/showList}}
{{#showList people}}{{first}} {{last}}{{/showList}}

Results:
A, B, and C
A, B, or C
A; B; C
A|B|C
Yehuda Katz, Alan Johnson, and Charles Jolley

Saying an Email Address

There are times when you will want to convert an email address into something

Data:
{
  email: "contact@vogovoice.com"
}

Template:
{{sayEmail email}}
{{sayEmail 'contact@vogovoice.com'}}
{{sayEmail 'john.doe@gmail.com'}}

Results:
contact at vogovoice dot com
john dot doe at gmail dot com

Pluralize

In many cases, you may not know if you have 0, 1 or more in the results and it can be complicated to say there 0 results or 1 results or 50 results and it would be helpful to automate this. This is when you will want to use the pluralize features. See the examples below.

Syntax: {{pluralize Integer 'String'}}

Data:
{
  connectors: {
    c1: {
      first: Object,
      length: 0
    },
    c2: {
      first: Object,
      length: 1
    },
    c2: {
      first: Object,
      length: 50
    }
}

Template:
You have {{connectors.c1.length}} {{pluralize connectors.c1.length 'result'}}.
You have {{connectors.c2.length}} {{pluralize connectors.c2.length 'result'}}.
You have {{connectors.c3.length}} {{pluralize connectors.c3.length 'result'}}.

Results:
You have 0 results.
You have 1 result.
You have 50 results.

mod

When there are cases where you want to use a Math mod to determine if something should happen within a template you can use the following syntax. This can be useful when trying to determine even or odd numbers, wanting to show something every nth time.

{{mod base divisor}}

Data:
{
  input1: 2,
  input2: 3
}

Template:
{{#if (mod input1 2) '===' 0}}{{input1}} is an even number.{{else}}{{input1}} is not an even number. It must be odd.{{/if}} 
{{#if (mod input2 2) '===' 0}}{{input2}} is an even number.{{else}}{{input2}} is not an even number. It must be odd.{{/if}}

Results:
This is an even number.
This is not an even number. It must be odd.
Was this article helpful?
Dislike 0
Previous: Creating Intents
Next: Data Breakdown