@raintech-oss/jovo-dew
v2.0.2
Published
Dew View Engine for Jovo
Downloads
188
Maintainers
Readme
Dew View Engine
Dew simplifies the creation of voice and bot applications by adding a view engine to your handler code.
Installation
You can install the plugin like this:
$ npm install @raintech-oss/jovo-dew
Add this plugin to the root list of plugins in app.ts
:
import { App } from '@jovotech/framework';
import { DewViewEnginePlugin } from '@raintech-oss/jovo-dew';
// ...
const app = new App({
plugins: [
new DewViewEnginePlugin({ /* ... */}),
// ...
],
});
Dew makes use of translations for i18n so the project must include them. This can be added to i18n in app.ts
:
import { App } from '@jovotech/framework';
// ...
const app = new App({
i18n: {
resources: {
en,
},
},
// ...
});
And there needs to be a corresponding file at src\i18n\en.json
.
Configuration
The following configurations can be added:
import { App } from '@jovotech/framework';
import { DewViewEnginePlugin } from '@raintech-oss/jovo-dew';
import audiosEn from './content/en/audios-file.json';
import { ViewVariables } from './ViewVariables';
// ...
const app = new App({
plugins: [
new DewViewEnginePlugin({
viewVariables: ViewVariables(),
audio: {
resources: {
en: audiosEn,
},
baseUrl: 'https://example.com/assets',
fallbackLocale: 'en',
defaultExt: '.mp3',
},
}),
// ...
],
});
viewVariables
: Object whose methods are called based on variables that need to be filled in output text. See View Variables for more information.audio
: Configuration values for audio variables used in output text. See Audio Variables for more information.
View Variables
Here is a sample ViewVariables.ts
file:
import { BaseViewVariables } from '@raintech-oss/jovo-dew';
export class ViewVariables extends BaseViewVariables {
constructor(jovo: Jovo) {
super(jovo);
}
blank(): string {
return ' ';
}
pause(): string {
return '<break time="500ms"/>';
}
fullName(): string {
return this.jovo.$session.data.fullName;
}
}
If the output text includes {{placeholders}}
as in "Welcome back {{pause}} to {{fullName}}"
, the Dew view engine will try to fill those placeholders in the following order:
- from a value added to
this.$dew.data.myKey
- function in ViewVariables.ts named the same as the placeholder
- constructed audio URL from audio resource audios-file.json where placeholder matches
variableName
. - if
filename
property in audios-file.json is empty, the value from thetext
property is used. - if still no match, the placeholder is replaced with a message that identifies the missing variable definition:
[missing variable: myValue]
Audio Variables
This feature allows for output to include audio files during production and use the text
value during development when audio files are not yet available.
The audio variables file (ex: audios-file.json) is in the following format:
[
{
"variableName": "sfx_success",
"filename": "success",
"text": "Submitted."
}
]
The fields are:
variableName
- matches the placeholder in the output textfilename
- used with the other values in the plugin configaudio
section to construct an audio URL:https://example.com/assets/success.mp3
text
- if thefilename
property is missing or empty, use this value
Usage
To access the Dew methods and properties, use this in a handler:
this.$dew
Here is a sample handler:
async LAUNCH() {
this.$dew.data.name = 'Mark';
const outputs = await this.$dew.getOutput(['Launch.WelcomeBack', 'SFX.Success', 'WhatNext']);
return this.$send(outputs);
}
The power of Dew is the nested structure of the src\i18n\en.json
file. Notice how the "WhatNext"
path groups a message
and a reprompt
and that a single call to this.$dew.getOutput(['WhatNext']);
includes both values in the output.
{
"translation": {
"Launch": {
"Welcome": {
"message": "Welcome, {{fullName}}."
},
"WelcomeBack": {
"message": "Welcome back {{name}}."
}
},
"SFX": {
"Success": {
"message": {
"speech": "{{sfx_success}}",
"text": "Item submitted."
}
}
},
"WhatNext": {
"message": "What next?",
"reprompt": "What do you want to do next?"
},
"Goodbye": {
"message": "See you next time.",
"listen": false
}
}
}
From the outside-in, there can be multiple nesting levels (usually 1 or 2) which acts at the path to identify the output. This is what is used in the $dew.getOutput
array parameter.
The next level matches the names of Generic Output Elements or custom keys:
message
(Jovo Output) - set to string, string[] or objectreprompt
(Jovo Output) - set to string, string[] or objectlisten
(Jovo Output) - set to boolean or objectquickReplies
(Jovo Output) - set to string[] or object[]card
(Jovo Output) - set to objectcarousel
(Jovo Output) - set to objectvv
(Custom) - set to function name inViewVariables
(vv
is short for ViewVariables)platforms
(Custom) - set to function name inViewVariables
apl
(Custom) - set to function name inViewVariables
When resolving using a function in ViewVariables
, return an output template as described in Output Templates:
// ViewVariables.ts
myOutput(): OutputTemplate {
return {
platforms: {
core: {
nativeResponse: {
custom: {
key: 'value1',
},
},
},
},
card: {
title: this.jovo.$t('someTitle'),
content: 'my content',
subtitle: 'this card from VV',
imageUrl: 'https://www.fillmurray.com/200/300',
imageAlt: 'Fill Murray',
},
};
}