Jexl Output Plugin for Jovo V4

Overview

This plugin for the Jovo V4 Framework allows you to use Jexl expressions within your output strings.

What is Jexl you ask? Jexl describes itself as "Javascript Expression Language: Powerful context-based expression parser and evaluator".

To start with a very basic example: Jexl expressions within strings look like "${1+1}". This would be evaluated to a string looking like "2". This looks trivial but when you learn that you can access the Jovo context using variables while support for libraries with Math expressions and Voca is included out of the box you might understand that soon you can do a lot more.

The plugin searches all Jexl expressions within your "message" and "reprompt" entries and will replace those with the evaluated result.

If there is no Jexl expression the string remains unchanged.

The resulting string is the utterance the user will receive from the system.

What does Jexl look like?

As said above Jexl expressions within strings look like "${ some jexl expression }". When using variables which have access to the Jovo context you can do a lot more. You should definitely visit the Jexl Homepage to understand the syntax options and possibilities.

Let us have a look at some examples:

Examples

• You have access to the complete set of functions of the JavaScript Math Library: "${ Math.max(1,2) }".

• This includes nested expressions: "Let me throw a dice for you. This time your magic number is ${Math.round(Math.random()*6)+1}."

You have access to the Jovo environment (details further below):

• Access the input values from the conversation: "You chose color ${$input.text}. Like a ${ $input.text == 'red' ? 'rose' : $input.text == 'green' ? 'cucumber' : 'rainbow'}"

• Access the Jovo session: "${$session.isNew ? 'Welcome stranger! ' : 'So here we launch again: '}"

• Access device specific information "${ 'SCREEN' in $device.capabilities ? 'Your device seems to have a screen.' : 'Your device does not have a screen'}",

• You also have access to the request object: "You seem to be located somewhere near ${$request.timeZone}"

• Access the user object: "${ $user.createdAt}"

And there is more:

• Use the power of the Voca string library: "Your utterance read backwards sounds like this: ${Voca.reverse($input.text)}"

List of supported libraries and environment variables

When using Jexl expressions you have access to the following libraries and environment variables:

  Math: Javascript Math Library
  Voca: Javascript Voca String Library
  $component: jovo.$component,
  $data: jovo.$data,
  $device: jovo.$device,
  $entities: jovo.$entities,
  $input: jovo.$input,
  $request: jovo.$request,
  $route: jovo.$route,
  $session: jovo.$session,
  $state: jovo.$state,
  $user: jovo.$user,
  $platform: jovo.$platform

Why should I use Jexl?

Using this plugin your strings become more powerful. The examples above show how to solve simple use cases that would otherwise require coding in your backend.

If you maintain your strings via a Voice CMS you may even be able to change the behaviour of your application without modifications to the code. This may be useful, but there is a warning required: you can shoot yourself in the foot when you decide to give content maintainers access to business logic!

Install

Install the plugin into your Jovo project:

npm install jovo-v4-community-plugin-jexl-output --save

Register the plugin in:

app.js:

const { JexlOutputPlugin } = require("jovo-v4-community-plugin-jexl-output");

app.use(
  // ... base imports
  new JexlOutputPlugin()
);

app.ts:

import { JexlOutputPlugin } from "jovo-v4-community-plugin-jexl-output";
app.use(
  // ... base imports
  new JexlOutputPlugin()
);

How to start

Replace your whatever WELCOME_MESSAGE with something like:

"Your magic number today is ${Math.round(Math.random()*6)+1}".

Now launch your voice app/skill/action multiple times.

Notice the magic?

License

Apache V2