JMango scripting language
From JMangoWiki
Language Overview
The JMango scripting language is a scripting language that allows you to design the various screens and prompts (and the order of their appearance) that the recipient of a JMango application will see on their phone. It is purposely simplified to allow for ease of use and to prevent the security pitfalls present in more complex languages. Its primary purpose is to gather a set of query responses from the user and return them to you (in the manner you specify when you create the application).
- Instructions are written line by line.
- Comment lines start with //.
- Labels start with #.
- String parameters are delimited with double quotes "".
Note that when a JMango script finishes executing (by encountering an END or EXIT command, or reaching the end of a script), the script will return the values associated with all string parameters that the user has selected.
Program Structure
Commands are processed sequentially line by line. Three instructions are supplied to support branching of program control: BRANCH_TO, BRANCH_BACK and GOTO. BRANCH_TO and BRANCH_BACK are used in combination to create subroutines for the compiled program. GOTO is a jump instruction that allows program execution to jump to a certain label in the script. Also note that comment and blank lines are ignored by the compiler.
Command line syntax
A command is a line in the script which has the following structure:
<Command Name> [<String Parameters>] [<Label>]
- Where:
- <Command Name> is one of JMango qualified commands.
- <String Parameter> is qualified string value, i.e. wrapped by double quote characters. For example "User name" is a string parameter. Some commands accept more than one string parameter. (The double quote character itself is not yet allowed inside string parameters.)
- <Label> is the name of the label that is defined in Label section. <Label> is only required for commands that involve branching, including GOTO and ITEM (when used in conjunction with BRANCH_TO command).
Comment line
There is no block comment in the language, but single line comments can be defined by starting a line with // (two forward slash characters followed by a space character).
Example:
// this is the comment line
Label
A label is used to mark a line so that it can be referred to in GOTO or BRANCH_TO...ITEM commands. A label line is a line starts with # (hash) character, followed by a space character. The label name is the next word from the # character.
Example:
// For label START, the line looks like this # START // the immediate command following the label is to be executed // when program branched or jumped to here MESSAGE "Hello" "Hello dude, it's me"
There cannot be duplicate labels in the script; a compile error occurs if this is detected.
Tree navigation
Using a combination of the BRANCH_TO command, labels, and BRANCH_BACK command allows tree-like structure of the program flow.
Script example
The above script example results in the following UI screen flow:
Workflow state
When user navigating through the workflow screens, the state of each screen (item selection and user inputs) is persisted. A default "Back" navigation button is attached to all the visible JMango screens, which allows backwards navigation through the workflow executed on the mobile device. On most phones, this "Back" button is mapped to the right action key (though this might be different depending on the type of phone).
A scripting example
A workflow diagram
The source script
//This program will allow to choose provided services # START //Services provided BANNER "J-MANGO Software" BRANCH_TO "srv" "Service Request" ITEM "Water" WATER ITEM "Electricity" POWER ITEM "Gas" GAS //Services type # WATER SELECT "water" "Water Problems List" ITEM "Pipe burst" ITEM "Leaking" ITEM "New Connection" GOTO LAST # POWER SELECT "power" "Power Problems List" ITEM "Fire" ITEM "Disconnection" ITEM "New Connection" GOTO LAST # GAS SELECT "gas" "Gas Problems List" ITEM "Fire" ITEM "Leaking" ITEM "New Connection" GOTO LAST //Services end //Input some information # LAST INPUT "name" "Your Name" ANY INPUT "phone" "Phone Number" NUMERIC //Message sent - application end # END
Code and Graphical Output
BRANCH_TO "serv" "Service Request" ITEM "Water" WATER ITEM "Electricity" ELECTRICITY ITEM "Gas" GAS
# WATER SELECT "water" "Water Problems List" ITEM "Pipe burst" ITEM "Leaking" ITEM "New Connection"
INPUT "name" "Your Name" ANY INPUT "phone" "Phone Number" NUMERIC
Script commands and syntax
HEADER
The HEADER command is used to specify a piece of text to be included at the beginning of the response message after the script has been executed. This command is invisible to the user. This command is useful to be used to specify context for server-client conversation.
There can be multiple header commands in the script, and when used in conjunction with BRANCH_TO command, different response message prefixes can be set based on user's selection.
Syntax
HEADER <header>
Where <header> is a string parameter to be appended to the beginning of the response text message.
DIVERT and DIVERT_DIGITS
DIVERT/DIVERT_DIGITS command is to redirect the response message to another mobile number. Normally, when a workflow message arrives, the response message is sent back to the source address of the payload. Including a DIVERT/DIVERT_DIGITS command in the workflow enables the response message to be sent back to another number instead.
Syntax
DIVERT <address> DIVERT_DIGITS <address>
<address> is a string parameter representing the mobile number of the redirected address; for example, +61418366896 or 0418366896. When using DIVERT_DIGITS command, the string parameter can only have digit characters.
MESSAGE
The MESSAGE command is to show a message with a title and message content to the user. The message requires the user to click OK to proceed.
Syntax
MESSAGE <title> <message content>
BANNER
This command sets the scrolling text to be shown on all screens in a JMango workflow. It is useful for branding. This command can be set at any point in the script but only applicable after being executed. Thus, it is recommended to include this BANNER command as soon as possible in the script.
Syntax
BANNER <scrolling text>
Where <scrolling text> is the text appearing on all the screens.
LOGO
The LOGO command is to show a logo screen, which a screen with a title and an image shown aligned in the middle of the screen.
Syntax
LOGO <logoid>
<logoid> is the id of the logo when uploaded to JMango gateway as a media file. Each media file is assigned with a unique id that is to be used in the script.
IMAGE
The IMAGE command is similar to LOGO command. The only difference is in the way the image is display. With this IMAGE command, the image is not re-sized and user can pan around to view the whole image using arrow buttons (if it is bigger than handset screen).
Syntax
Image <imageid/url> <waitingmessage> <timeout>
<imageid/url> is the id of the image when uploaded to JMango gateway as a media file or the link of image from the Internet. Each media file is assigned with a unique id that is to be used in the script.
<waitingmessage> is the text message which is displayed while image is being downloaded
<timeout> number of seconds after that the script move on to next screen without pressing "Next" button. Value of "0" will disable this automation.
PAGE
The PAGE command allows the developers to display many images and text messages all together in one screen.
Syntax
PAGE <title> ITEM TEXT <text message> ITEM IMAGE <imageid/url> ...
The PAGE command accepts two types of ITEM. To add text message to the page, ITEM TEXT should be used, while ITEM IMAGE is used to add an image to the page. Many items can be added and displayed in the same order of the addition.
GRID_IMAGE
The GRID_IMAGE command allows developers to display a selection screen in form of a grid of images.
The behavior of GRID_IMAGE command is similar to BRANCH_TO command. By choosing an image in the grid, the user will jump to corresponding labels in the workflow.
Syntax
GRID_IMAGE <Parameter name> <Title> <columnsNb> ITEM <imageid> <text> LABEL1 ...
Where, for GRID_IMAGE:
<Parameter name> is a string parameter specifying the name of the variable, in which we store the selection made.
<Title> is a string parameter specifying the title of the screen.
<columnsNb> is an integer parameter specifying how many columns our Grid will be divided to. This parameter is also used to determine the size of each cell in the grid.
For ITEM:
<imageid> is an integer parameter which corresponds to the id of an image file uploaded in JMango gateway.
<text> is a string parameter specifying the text content to be displayed in the same cell, below the image.
TABLE
The TABLE command allows developers to display data in the form of table.
User can navigate to any row in the table and choose Next to select it. By selecting a row, user will be moved to the appropriate address in the workflow.
Syntax
TABLE <TableTitle> <Column_1 header> <Column_2 header> <Column_3 header> ... ITEM <Column_1 data> <Column_2 data> <Column_3 data> <LABEL> ...
Table can have many columns, which is up to the developers to decide. The number of columns is determined by how many column headers are entered following the TABLE keyword.
<TableTitle> is a string parameter specifying title for the table.
<Column_k header> is a string parameter specifying the name/header for the k-th column
Each ITEM in the table should contain the exact number of data as the number of columns in this table.
Please note that in contrast to BRANCH_TO and GRID_IMAGE commands, where ITEM requires a LABEL associated, here in TABLE the ITEM'S LABELs are optional.
DOWNLOAD
This command is to instruct the mobile phone to download media content from JMango gateway. The media file is uploaded and assigned with a unique id that can be referred to in this command. This command behavior is similar to EXECUTE command.
Syntax
DOWNLOAD <fileid>
Where <fileid> is the id of the media file uploaded to JMango gateway.
TAKE_PHOTO
This command will allow a user to take a photo with their device and then upload it.
Syntax
TAKE_PHOTO <varname> <quality> [exception]
Where
@varname: name of photo and ref
@quality: small, medium, large, xlarge
@[exception]: BRANCH_TO or GOTO command in case phone do no have camera
PLAY
This command uses the phone's media player to play either an audio or video file from a direct URL feed. As it uses the phone's media player, MP3 and 3GP (a type of MP4) are the recommended formats.
Syntax
PLAY <file_link> <title> <exception>
Where
@file_link: actual link to the media file
@title: title of the PLAY screen
@exception: label to be executed in case exception occurs
INPUT
This command provides a GUI screen with a text input box to the user to retrieve user inputs. A parameter name is provided in the command to set the name of the user input data when included in the response message. A default input value is set as part of the input parameter. User input data can be restricted by specifying the type of response desired. Implementation of user input restriction by specifying this type depends on the capability of the mobile device that the client application runs on.
Syntax
INPUT <parameter name> <label> <ANY|EMAILADDR|NUMERIC|PHONENUMBER|URL|DECIMAL|PASSWORD> <Min length> <Max length>
GOTO
The GOTO command allows the workflow execution engine to jump to a specific workflow instruction immediately following the given label rather than proceeding to the next instruction in sequence. There is no user screen or response data associated with this instruction.
Syntax
GOTO <label>
SELECT and SELECT_MULTI
These commands provide users a UI screen with a list of items to select from. The SELECT command is single selection and SELECT_MULTI is a multiple selection. The user selection is included in the response message identified by the parameter name. In case of a multiple selection, the selected values are separated by a delimiter character in the response value data.
Syntax
SELECT or SELECT_MULTI command is followed by ITEM definitions (one per line).
SELECT <parameter name> <title> ITEM <item name> ITEM <item name> ITEM <item name> SELECT_MULTI <parameter name> <title> ITEM <item name> ITEM <item name> ITEM <item name>
BRANCH_TO
These commands provide users a list of items to select. Upon selection of an item, execution of the workflow is branched to the corresponding label. The behavior of this command is similar to SELECT command, except that a branch is made based on the user selection. Once the workflow execution starts executing from the new target instruction, it follows the default sequential order. When a BRANCH_BACK command is then encountered, the workflow execution engine returns to the statement following the previous BRANCH_TO command. However, BRANCH_TO command does not require BRANCH_BACK command to operate -- the workflow can consequently branch to the last command without returning to the branch menu.
Syntax
BRANCH_TO command is followed by ITEM definitions (one per line)
BRANCH_TO <parameter name> <title> ITEM <item> <label> ITEM <item> <label> ITEM <item> <label>
- <parameter> name can be empty qualified string i.e. "". If this is the case BRANCH_TO command is strictly a switch, i.e. domain path based on tree of selected item is not applied.
BRANCH_BACK
The BRANCH_BACK command is used to navigate back from branching. A workflow could have multiple branches specified resulting in a tree-like structure. BRANCH_BACK command allows navigation upwards in this tree structure.
Combination of label and BRANCH_BACK command allows combining a group of workflow commands in to a routine, which can be referred to multiple times during the workflow execution.
Syntax
BRANCH_BACK
STORE_PERMANENT
The STORE_PERMANENT command instructs the workflow execution to store the whole payload script to persistent storage on the user's cell phone. This script can then be called up again by the user based on the specified title. This command does not result in any user data in the response message.
Syntax
STORE_PERMANENT <title>
STORE_SCRIPT
The STORE_SCRIPT command is an alternative command of STORE_PERMANENT. It has functionality and purpose of STORE_PERMANENT
Syntax
STORE_SCRIPT <title>
Example code
// Save "A test script" in Application Inbox STORE_SCRIPT "A test script" MESSAGE "Hello" "This is a hello world message" CANCEL
CLEAR_PERMANENT
This command clears all the persistent workflow payload data previously saved by STORE_PERMANENT command. Execution of this command does not result in any data in the response message.
Syntax
CLEAR_PERMANENT
REMOVE_SCRIPT
This command allows the developer to delete their own script which is stored on the device by STORE_PERMANENT command.
Syntax
REMOVE_SCRIPT [optional_script_name]
If script name is not provided, the current being executed permanent script is removed. This can be useful in updating the permanent script and remove it completely
CALL_SCRIPT
This command will allow to call another script in Application box
Syntax
CALL_SCRIPT "another_script_name" [label]
EXECUTE
This command makes a request to the mobile device operating system to retrieve a URL address. The result could be making a phone call or launching the internet browser on the phone to the specified URL address. Behavior of this command might vary across different device models due to device capabilities.
Syntax
EXECUTE <url_address>
SEND_SMS
SEND_SMS command will send a text message to specific destination
Syntax
SEND_SMS [number] [message] [failed label]
Where
@number: destination phone number
@message: text message need to be sent
@fail label: use Label in case of error occur
IF Statement
IF statement for basic decision marking situation between true and false value. Now we can use this command to compare date data
Syntax
IF <condition> TRUE_LABEL IF <condition> TRUE_LABEL FALSE_LABEL
CONFIGURATION
The CONFIGURATION command allows you to change various features concerning how the response message (consisting of all the user's responses) is formatted. This command when included in the payload data can change the delimiter characters of the response message as well as specifying whether or not the name part is included in the response message.
Syntax
CONFIGURATION <configuration_string>
LOCATION
The LOCATION command uses the LOCATION API (JSR-179) on the mobile phone to provide you the location of the phone.
Syntax
LOCATION <variable1_name> <variable2_name> <NOT_SUPPORTED_LABEL>
Where
- variable1_name specifies the variable to store the longtitude of the phone.
- variable2_name specifies the variable to store the latitude of the phone.
- NOT_SUPPORTED_LABEL is the address in the workflow that will be executed in case the mobile phone does not support Location API (JSR-179) or if some errors prevent reading the phone's location.
SYSTEM_PROPERTY
This command instructs the workflow execution to read a system property and return the result in the response. The parameter name that is associated with the response data is the same as the system property name if parameter name is omitted.
Syntax
SYSTEM_PROPERTY <property_name>
Where
- <property_name> is the system property to be read by JMango. On J2ME platform, examples of these properties are:
- microedition.profiles
- microedition.configuration
The full list of J2ME specific system properties can be found here:
NOP
This is a no-operation command. It is useful when used in conjunction with labeling and branching
Syntax
NOP
CANCEL
The CANCEL command terminates execution of the script without sending the user's response data. Using this command in conjunction with BRANCH_TO command gives JMango script the capability to cancel the user's response data if user chooses certain option.
Syntax
CANCEL
EXIT
This command cancels all the user inputs in the current workflow execution and exits the JMango application.
Syntax
EXIT
or
EXIT SCRIPT
or
EXIT JMANGO
END
This command indicates the end of the workflow execution. In a normal script, if there is no END command, the workflow execution is finished when the last command based on index is executed. Using END command in conjunction with BRANCH_TO command simplifies the script.
Syntax
END
SUBMIT
This command is similar to SYNC_RESPONSE command. In addition, SUBMIT command is able to submit data to another aplication when required.
Syntax
SUBMIT
or
SUBMIT "application name"
SYNC_RESPONSE
This command will synchronize with the back-end system. In another word, it will collect application variables and transfer to the back-end system.
Syntax
SYNC_RESPONSE
RESPONSE_HTTP
This command is similar to SYNC_RESPONSE command. The difference of the RESPONSE_HTTP is a flag therefore when reach EOF or END command, data is sent via HTTP eof script - implicit, send if there is data, go back to inbox if no data
END - explicit EOF invokes send via SMS or via GET HTTP
Syntax
RESPONSE_HTTP
VAR and CLEAR_VAR
These two commands allow setting a variable with a value, which can be Integer type or String type. The Integer type is automatically detected if it is an integer.
Syntax
VAR "name" "value" VAR "name" "default value" http://www.application.com/getremotevalue?asdfdsaf&asdfadsf "waiting message" CLEAR_VAR "name"
3rd parameter is optional to fetch the variable value from an URL. 4th parameter is also optional to show the waiting text while the phone is retrieving data from the URL
APPEND
This command is a string appending operation that appends the second operand to the variable name. The target variable becomes String type if it is not yet a String type. So appending a string to an Integer makes it becoming String. The operand can contain a reference to other variables so that other variables' values are replaced to the string before it is appended to the target variable.
Syntax
APPEND "varname" " value $anothervarname"
INCREMENT
This command is an Integer operation. It increments the Integer variable by the specified amount.
Syntax
INCREMENT "varname" 1
The above command increment varname by 1.
VAR_SUFFIX and END_SUFFIX
These commands allow suffixing of variable name with another variable's value. It can be useful in multiple branches looping to gather collect use input data multiple times.
Syntax
VAR "suffix" "1" ... VAR_SUFFIX "suffix" ... END_SUFFIX ...
VAR_PREFIX and END_PREFIX
These commands allow prefixing of variable name with another variable's value. These are similar to VAR_SUFFIX and END_SUFFIX commands. It can be useful in multiple branch looping to gather collect use input data multiple times.
Syntax
VAR "prefix" "1" ... VAR_PREFIX "prefix" ... END_PREFIX ...
CAL
This command allows the script to perform some simple calculations with attributes can be variables.
Syntax
CAL <varname> <formula>
<varname> name of the variable you want to put the result in
<formular> the formula to calculate
ADD_COMMAND
This ADD_COMMAND will add a command to all the later displayed application's screens. By selecting that newly added command, users will jump to a specific address in the workflow, declared in this ADD_COMMAND.
These commands can be removed using DELETE_COMMAND.
Syntax
ADD_COMMAND <command name> <LABEL>
<command name> name of the added command to be displayed in all the application's screens.
<LABEL> is the destination address (in the workflow) for the newly added command.
DELETE_COMMAND
This DELETE_COMMAND is used to remove the commands added by ADD_COMMAND earlier. DELETE_COMMAND cannot remove the basic commands of the screen (like Exit, Next, Back) but only the ones added by ADD_COMMAND.
Syntax
DELETE_COMMAND <command name>
<command name> the name of the command to be deleted from the screens. It has to be one of the commands added by ADD_COMMAND.
CLEAR_CACHE
This CLEAR_CACHE is used to clear the cache of the mobile phone. It can erase only one record each time.
Syntax
CLEAR_CACHE <record id>
<record id> is a string parameter that identifies the cached resource.
QRCODE
This QRCODE is used to create the 2D-QR-code for the text content provided. The text will be encoded and displayed as an image.
Syntax
QRCODE <data to encode>
<data to encode> is a string parameter.
CHECK_VERSION
This CHECK_VERSION is used to check if the version of the actual software is enough to execute the script.
Syntax
CHECK_VERSION <version>
<version> is a string parameter.
Creating a Branded Application
By default, applications are shown on the mobile device under the JMango application. However, you can also create a branded application to give it your own look and feel. You can speficy the colours of the various backgrounds and fonts (see below) and the images that are displayed in the download message and as the applicaiton icon. You will need to play around with the colours and images to work out what looks best on various mobile devices.
In order to have your branded application created you will need to request this via email to your local JMango support centre. Please specify the colours and images you would like to use.
Colours
The following areas can have their own colours assigned to them (colours can be in any hexidecimal colour range i.e. 0x000000 to 0xFFFFFF):
- Header
- Background
- Font
- Body
- Background
- Font
- Selected Font
- Footer
- Background
- Font
