ut-ussd - USSD menu engine

Configuration options

``javascript
{
utUssd: {
ussd: {
exposeState: 'true|false', // this will expose runtime
// state if set to true, defaults: false
// refresh: gets refreshed on every cycle;
// static(default): sets only once and will expire
// in predefined period of time (timeOut);
expireRule: 'refresh|static',
timeOut: 1000, // expiration period definition
shortCodes: { // short codes
"*877#": "menu/entrance"
},
maintenanceModeState: "menu/maintenance", // maintenance mode state
wrongInputState: "error/wrongInput", // wrong input state
resumeState: "menu/resume", // resume state
strings: [ // USSD strings
"8771*1#",
"8771*2#",
"8772*1#",
"8772*2#",
"8772*3#",
"8773*1#",
"8773*2#",
"8774#"
],
defaultPhone: "1234", // default phone number for the simulator
defaultShortCode: "*131#", // default short code for the simulator
charsCount: true, // if characters count should be visible in the simulator
// To display a slogan with the respective text above the phone number input
// (no slogan will be displayed by default)
slogan: 'Test'
}
}
}
`

Views

USSD menu is defined in template files named view.xml, each one being in a separate
folder. Folders are usually structured to mirror the USSD menu structure.

For example:

`text
ussd
├── components
| ├── back.xml
| ├── backToHome.xml
| └── footer.xml
└── menu
├── home
| └── view.xml
├── login
| └── view.xml
└── error
| ├── runtimeError
| | └── view.xml
| └── wrongInput
| └── view.xml
└── account
├── balanceEnquiry
| └── view.xml
└── miniStatement
└── view.xml
`

The template files are JavaScript template literals, passed to
ut-function.template engine.
Each view file can contain some specific markup as in the below examples:

1. Links - links are defined with the tag ,
where the attribute id represents the USSD input, and href
represents the next menu to show when this input is received.

`xml
Menu
1. Account information
`

1. Expressions - the standard syntax ${} applicable to JS template
literals can be used to define expressions, either simple ones like:

`text
${params.system.prevState}
`

or more complex like iterating over array:

`text
${
params.miniStatement.map(
rec => ${rec.amount} on ${rec.postDate}
).join(
)
}
`

or for conditional rendering:

`text
${
params.view === 'pin' ? 'Please enter your PIN' :
params.view === 'wrongPin' ? Wrong PIN.
Please try again' :
'Unexpected Error'
}
``

1. Translations - the USSD template engine includes the function T,
which can be used to translate text:

`text
${TPlease enter your PIN}
`

The syntax is based on JS tagged templates.

1. Includes - repeated fragments can be included in multiple views using the syntax:

`text
Some menu

${include('../../components/back.xml')}
`

The essential API objects available in the views
${} expressions are:

- All node.js global objects
- T - the function used for translation
- include - the function used to include fragments
- params - object, containing the template parameters

The essential tags available in the views are:

- link - for defining links to other menus
-
- for line breaks

Controllers

Each menu can have an optional controller.js file,
which handles actions related to the menu.
This file resides in the same folder as the menu's
respective view.js.
There are two optional actions, that can be defined:

1. send: This is executed before rendering the current
menu. It can call other services to fetch data to be
displayed in the menu.
1. receive: This is executed after receiving the
response for a particular menu.

Controllers can be defined as object:

`js
module.exports = {
async send(params) {
// some processing
return params;
},
async receive(params) {
// some processing
return params;
}
};
`

Controllers can be also be defined as a function, returning an object.
This is useful when external API must be called using
the familiar destructuring syntax: import:{}.

>Note that import is the only available property at the moment.

`js
module.exports = ({
import: {
subjectObjectPredicate
}
}) => ({
async send(params) {
try {
const result = await subjectObjectPredicate({});
// some processing
return params;
} catch (error) {
params.error = error;
this.redirect('menu/error/runtimeError');
return params;
}
}
});
`

The official API objects available in the controllers are:

- import: {subjectObjectPredicate} - proxy for obtaining external API
- this.redirect(view)` - for selecting the next view