Commands

Index

Programming
Data
Display
Operations
Logic
Comparison
Navigation
Embedded

# Programming

Command	Description
`if`	Conditional execution of commands.
`call`	Calls an endpoint to fetch commands to be executed.
`call-js`	Calls a Javascript function to fetch commands to be executed.
`throw`	Stops the execution of the current list of commands.
`qs`	Gets a query string parameter of the current page location.
`alert`	Shows or hides an alert popup.
`restart`	Clears all data and resets the story to the beginning.
`console`	Shows a message in the browser console.

# `if`

Conditional execution of commands.

Argument

List of sequential conditions to be tested.

Condition Attributes

cond

Function with conditional.

program

One or more commands to be executed if the condition is met.

Examples

{"if": [
    { 
        "cond": {"==": [{"v": "result"}, "HIGH"]},
        "program": { "jump_page": "page_high" }
    },
    { 
        "cond": {"==": [{"v": "result"}, "LOW"]},
        "program": { "jump_page": "page_low" }
    },
    { 
        "program": { "next_page": true }
    }
]}

Example with multiple conditions and a list of commands:

{"if": [
    { 
        "cond": {"and": [
            {">=": [{"v": "age"}, 30]},
            {"<=": [{"v": "age"}, 50]},
            {"==": [{"v": "sex"}, "M"]}
        ]},
        "program": [
            { "save": ["profile", "2"] },
            { "jump_page": "page_profile_2" }
        ]
    }
]}

# `call`

Calls an endpoint to fetch commands to be executed.

Arguments

endpoint

The URL to be called to fetch the commands. The URL can be an absolute or relative path.

data optional

List of parameters to be sent to the endpoint. It could be a variable key or a key-value parameter.

For key-value parameters, the value can be a literal or a single command call returning a literal.

If not informed, all variables that do not start with "_" (underscore) will be sent.

By default, the value property of the variable is used. If the value is empty, the id or label is used instead.

Examples

{"call": { "endpoint": "https://example.com/endpoint/msg" } }

Example with variables and relative URL:

{"call": { 
    "endpoint": "/api/send_email", 
    "data": [ 
        "name", 
        "email",
        { "result": {"v": "res"} }
    ]
}}

Server processing

The instructions below show how to respond to requests initiated by the call command.

Request

A POST request will be called on the URL endpoint, using the endpoint attribute.

The following parameters will be sent in the BODY of the request:

Parameter	Description
`hash`	the root attribute `hash`.
`origin`	The protocol, hostname, and port number of the caller's URL.
`data`	JSON with the parameters specified in the `data` attribute.

Response

The server must respond with a JSON message containing the following parameters:

Parameter	Description
`ok`	`true`
`res`	List of commands to be executed.

if an error occurs:

Parameter	Description
`ok`	`false`
`error_msg`	The error message to be shown to the user.
`error_code`	The error code.

Example of response:

{   
    "ok": true,
    "res": [
        {"save":["token", "123"]},
        {"next_page":true}
    ]
}

An error response:

{   
    "ok": false,
    "error_msg": "Invalid request",
    "error_code": "ERROR_INVALID_REQUEST"
}

# `call-js`

Calls a Javascript function to fetch commands to be executed.

UNDER CONSTRUCTION

# `throw`

Stops the execution of the current list of commands.

Argument

The message shown to the user.

Example

{"throw": "Error found"}

# `qs`

Gets a query string parameter of the current page location.

Argument

Parameter name in the location query string.

Return

The value associated with the parameter.

Example

To get the parameter sid, considering the current location https://p.devgutt.github.io/evaluatly/acc/tst?sid=234:

{"qs": "sid"}

# `alert`

Shows or hides an alert popup.

Argument

is

The alert type.

Values	Description
`error`	Shows an error alert popup (default)
`warning`	Shows a warning alert popup
`info`	Shows an information alert popup
`success`	Shows a success alert popup

msg

Message to be displayed.

Accepts text formatting and variables.

interval optional

The period in milliseconds that the alert will be displayed. (1000 milliseconds = 1 second). The default is 3000 milliseconds.

Use -1 to not hide the alert automatically.

style optional

Style to be applied to the alert as CSS key-value pairs.

The values can be a literal value or a single command call returning a literal value.

Example

{"alert": {"is": "info", "interval": 5000, "msg": "Hello there!"}}

# `restart`

Clears all data and resets the story to the beginning.

Argument

true

Example

{"restart": true}

# `console`

Shows a message in the browser console.

Used for debugging.

Argument

Expression or list of expressions.

An expression can be a literal value or a command.

If a list is used, the values are concatenated before the display.

Examples

{"console": "Checkpoint 1"}

Example with a list:

{"console": [ "hello ", {"v": "name"} ]}

# Data

Commands to manipulate variables.

The variables are saved on a data table for the session, and it is erased when the tab or browser closes.

Optionally, you can store the variables to be available in the future after the session is closed.

Command	Description
`v` (value)	Gets the `value` of a variable.
`i` (id)	Gets the `id` of a variable.
`l` (label)	Gets the `label` of a variable.
`prop`	Gets the property of a variable.
`save`	Saves a variable in the data table.
`delete`	Deletes a variable in the data table.
`store`	Stores a list of variables on the local storage.
`restore`	Restores a list of variables from the local storage.
`remove`	Removes variables from the local storage.

# `v`

Gets the value of a variable.

Argument

Variable name.

Return

Value of the variable.

Example

{"v": "name"}

# `i`

Gets the id of a variable.

Argument

Variable name.

Return

Id of the variable.

Example

{"i": "check_1"}

# `l`

Gets the label of a variable.

Argument

Variable name.

Return

The label of the variable.

Example

{"l": "radio_1"}

# `prop`

Gets the property of a variable.

Argument

[key, prop]

key

Key of the variable.

prop property

The name of the property.

Return

The label of the variable.

Example

{"prop": ["radio_1", "label"]}

# `save`

Saves a variable in the data table.

The variable will be created if it does not exist. If it already exists, the value will be replaced by the new one.

Argument

[key, prop, value]

key

Key of the variable.

prop optional

The name of the property. Defaults to value.

value

A literal value or single command call returning a literal.

Examples

{"save": ["score", "value", 60]}

Example using conditional:

{ "if": [
    { 
        "cond": {"<=": [{"v": "score"}, 20]},
        "program": {"save": ["result", "value", "LOW"]}
    },
    { 
        "cond": {">=": [{"v": "score"}, 80]},
        "program": {"save": ["result", "value", "HIGH"]}
    },
    { 
        "program": {"save": ["result", "value", "NORMAL"]}
    }
] }

Example using command call:

{"save": ["sum", {"+": [23, 12, 45]}]}

# `delete`

Deletes a variable in the data table.

Argument

key

Key of the variable.

Examples

{"delete": "score"}

# `store`

Stores a list of variables from the data table to the local storage.

Argument

List of variables.

Examples

{"store": ["name", "email"]}

# `restore`

Restores a list of variables from the local storage to the data table.

Argument

List of variables.

Examples

{"restore": ["name", "email"]}

# `remove`

Removes variables from the local storage.

Argument

List of variables, or all to delete all variables of the local storage.

Examples

{"remove": ["name", "email"]}

Delete all variables on the local storage:

{"remove": "all"}

# Display

Command	Description
`sub`	Applies text formatting and variables to a text.

# `sub`

Applies text formatting and variables to a text.

Argument

Text to process the substitutions.

Return

The text processed.

Examples

{"sub": "The color is {{color|upper}}"}

# Operations

Applies the operator to a list of values.

Operation	Description
`+`	Sums or concatenate the values
`-`	Subtracts the values
`*`	Multiply the values
`/`	Divides the values

Argument

List of values to perform the operation desired.

The values can be a literal or a single command call returning a literal.

The operation is executed sequentially from left to right.

Return

The result of the operation.

Examples

{"+": [43, 12, 2]}

Example using command call:

{"+": [43, 12, {"v": "result"}]}

Example concatenating text:

{"+": ["Your name is ", {"v": "name"}]}

You can use text formatting and variables for this type of operation.

Example with multiple operations:

{"*": [ {"+": [ {"v": "X"}, {"v": "Y"} ]}, 100 ]}

# Logic

Boolean operations.

Command	Description
`and`	Boolean "and" operation
`or`	Boolean "or" operation
`not`	Inverts the boolean value

Argument

For and and or operations: List of values to perform the operation desired.

For not operation: Value to be inverted.

The values can be a literal or a single command call returning a literal.

Return

Result of the operation: true or false.

Examples

{"and": [ {"v": "isFirst"}, true ]}

Example with inversion:

{"not": {"v": "isFirst"}}

Example with complex operations:

{"and": [
        {"<": [{"v": "result"}, "100"]},
        {">": [{"v": "result"}, "30"]},
        {"!=": [{"v": "result"}, "70"]}
    ]
}

# Comparison

Compares two values.

Command	Description
`==`	Equal
`!=`	Not equal
`>`	Greater than
`>=`	Greater than or equal to
`<`	Less than
`<=`	Less than or equal to

Argument

A comparison pair: [value1, value2].

The values can be a literal or a single command call returning a literal.

Return

Result of the operation: true or false.

Examples

{"==": [{"v": "result"}, 70]}

{">": [{"v": "result"}, 70]}

# Navigation

Command	Description
`next_page`	Navigates to the next page in the story.
`previous_page`	Navigates to the previous page in the story.
`reload_page`	Reloads the current page in the story.
`jump_page`	Jumps to a page with a given id.
`redirect`	Redirects to a URL.

# `next_page`

Navigates to the next page in the story.

Argument

true

Examples

{"next_page": true}

# `previous_page`

Navigates to the previous page in the story.

Argument

true

Examples

{"previous_page": true}

# `reload_page`

Reloads the current page in the story.

Argument

true

Examples

{"reload_page": true}

# `jump_page`

Jumps to a page with a given id.

Argument

The id of the destination page.

The values can be a literal or a single command call returning a literal.

Go to Story for more information about pages.

The values can be a literal or a single command call returning a literal.

Examples

{"jump_page": "page_result"}

Example using command:

{"jump_page": {"v": "savedPageId"}}

Example using conditional jumping:

{"if": [
    {
        "cond": {">=": [{"v": "result"}, 80]},
        "program": {"jump_page": "page_high"}
    },
    {
        "cond": {"<=": [{"v": "result"}, 20]},
        "program": {"jump_page": "page_low"}
    },
    {
        "program": {"jump_page": "page_normal"}
    }
]}

# `redirect`

Redirects to a URL.

If the story is embedded, the parent will be redirected.

Arguments

url

The URL for redirection.

The URL can be a literal or a single command call returning a literal.

data

List of parameters to be submitted to the URL. It could be the name of a variable or a key-value parameter.

By default, the value property of the variable is used. If the value is empty, the id is used instead.

For key-value parameters, the value can be a literal or a single command call returning a literal.

method

The method for redirection.

Values: get (default) or post.

Examples

Example of get redirection:

{"redirect": { 
    "data": ["name", "email"], 
    "url": "https://mywebsite.com/show" 
    } 
}

Example of post redirection:

{"redirect": { 
    "method": "post",
    "data": [ 
        "name", "email", 
        {
            "result": {"v": "result"},
            "token": "123"
        } 
    ],
    "url": "https://mywebsite.com/result"
    }
}

# Embedded

Command	Description
`parent`	Communicates with the parent window.
`has_parent`	Indicates whether the story is embedded.

# `parent`

Communicates with the parent window.

This command only works for embedded stories.

Close the embedded window

Argument

action

close

Example

{"parent": { "action": "close" }}

Sends a message to the parent window

Arguments

action

message

data

List of parameters to be sent with the message. It could be the name of a variable or a key-value parameter.

By default, the value property of the variable is used. If the value is empty, the id is used instead.

For key-value parameters, the value can be a literal or a single command call returning a literal.

Example

{"parent": {
    "action": "message",
    "data": [
        "name", 
        "email", 
        {"extra": "SOURCE"}
        ]
    }
}

# `has_parent`

It indicates whether the story is embedded.

Argument

Boolean to be matched with the response.

Return

true if it matches the argument or false otherwise.

Example

{"has_parent": true}

Commands

Index

# Programming

# if

Argument

Condition Attributes

Examples

# call

Arguments

Examples

Server processing

# call-js

# throw

Argument

Example

# qs

Argument

Return

Example

# alert

Argument

Example

# restart

Argument

Example

# console

Argument

Examples

# Data

# v

Argument

Return

Example

# i

Argument

Return

Example

# l

Argument

Return

Example

# prop

Argument

Return

Example

# save

Argument

Examples

# delete

Argument

Examples

# store

Argument

Examples

# restore

Argument

Examples

# remove

Argument

Examples

# Display

# sub

Argument

Return

Examples

# Operations

Argument

Return

Examples

# Logic

Argument

Return

Examples

# Comparison

Argument

Return

Examples

# Navigation

# next_page

Argument

# `if`

# `call`

# `call-js`

# `throw`

# `qs`

# `alert`

# `restart`

# `console`

# `v`

# `i`

# `l`

# `prop`

# `save`

# `delete`

# `store`

# `restore`

# `remove`

# `sub`

# `next_page`

# `previous_page`

# `reload_page`

# `jump_page`

# `redirect`

# `parent`

# `has_parent`