Pages and forms

Expressions

Form expressions are "evaluations" or "calculations" used when building forms in Toqio Workflow Design. Form expressions are available in the majority of the attributes used in form components, allowing you to bind components together and define specific form behaviour.

Form expressions are defined using matching double curly braces: {{ and }}, and the payload holds the form data the user has to view or fill in. Expressions are built using values from the payload: literals (numbers, strings, and booleans) and a few special values.

You can use any value from the payload, including literals (numbers, strings, and booleans) and (additional data) inside an expression.

To access attributes of objects you can use the dot operator object.attribute.

To access items in an array you can use brackets array[index]:

{{true}}
{{5}}
{{"hello"}}
{{disabled}}
{{$currentUser.id}}
{{$currentUser.memberGroups.has('workflowsUser')}}

You can use logical operators:

{{!disabled}}
{{age > 5}}
{{length == 5}}
{{length <= 2}}
{{disabled || invisible}}
{{alive && kicking}}

You can use mathematical operators, string concatenation, and conditionals:

{{age + 5}}
{{age - 1}}
{{age / 2}}
{{age * 2}}
{{age % 2}}
Hello {{name}} {{surname}}, have a nice {{dayphase}}
{{name + " " + surname}}
{{age < 16 ? 'child' : 'adult'}}

You can also use Ecmascript methods and attributes of the objects resolved in expressions. For example:

{{case.dueDate.toLocaleDateString()}}
{{tweet.length}}
{{names.join(", ")}}
{{colors.indexOf['red']}}

You can use a pipe operator |>.
(It executes the function to its right, passing the parameter from the left side):

{{date2 |> flw.formatTime}}
{{date2 |> flw.formatDate}}

You can use all of them together:

{{user.age + 1 == 21 && !user.admin ? "Next year you can become an admin" : user.admin ? "admin" : "go away " + user.name }}

Scope

Input components assign their value into the payload. For example, if a text component has value {{name}} when the user writes Jordan in that input, the payload will get an attribute name with value Jordan. The expression in the value attribute of an input component is a special expression that doesn't allow operators.

Most container components, like panels and subforms, also allow you to define a value. This scopes all the values in the components inside the container. For example, you can define this form:

panel: value={{address}}
   text: value={{name}}
   text: value={{number}}

When the user fills in the name with Baker Street and the number with 221B, the payload will become:

address: {
  name: "Baker Street",
  number: "221B"
}

Components can write data to the payload in their scope and their children's scope but not in their ancestors'.

To access and edit data from its ancestors' scope, components can use the special keyword $payload that provides the whole payload. See this complete example:

checkbox: label="Show surname" value={{showSurname}}
panel: value={{client}}
  text: value={{name}}
  text: value={{surname}} visible={{$payload.showSurname}}

In some cases, it is necessary to access the parent scope.

In the following example we want to ensure children are +14 years old when their families don't hire a nursery service. To do that we use the $itemParent keyword to access the parent scope of the component.

subform: value={{families}} [[multipleEntries=true]]
  boolean: label=Nursery service value={{nursery}}
  subform: value={{children}} [[multipleEntries=true]]
    number: label=Age value={{age}} [[min={{$itemParent.nursery ? undefined : 14}}]]

$itemParent is read-only, so it can't be used to alter parent scope variables.

Multiple items in a subform

A subform is a great way to create reusable form components and with the sub-scope, it even can be used in different data structures, as long as the data binding within the subform stays the same.

But there is more to that component as it can also be used with multiple elements resulting in a collection (array) data structure.

Assume we have an array of phone numbers on a customer data form, each record holds the phone number and its type to have a data structure like this:

{
  "phoneNumbers": [
    {
      "number": "+1 555 123 456",
      "type": "main"
    },
    {
      "number": "+1 555 222 333",
      "type": "mobile"
    }
  ]
}

We can add a subform to our customer data form and scope it to {{phoneNumbers}} and of course with multiple elements turned on. The input fields within the subform can then bind to {{number}} and {{type}} respectively.

If we need some data from outside the array, like the editable flag we used before, we can use the keyword $itemParent to gain access to the scope just outside our multi-element subform (array), like {{$itemParent.isEditable}} as an example.

Sometimes you would like to render stuff on such a multi-element subform only on the first element or on every element, but the last and so forth. For this purpose you can use the $index keyword.

When you only want to render a component on the first element (row), you can use the expression {{$index != 0}} for the ignored attribute, so the component is ignored on every row other than the first one (index 0).

Likewise, if you want to render a horizontal line between the elements, but obviously not on the last element (row), you can use {{$index == $itemParent.nameOfArray.length - 1}} as the ignored attribute, where that component would be ignored on the last element in the array.

Special expression values

Here are some special expressions and what they do:

{{$payload}}
Root path used to access any payload value (e.g. {{$payload.mySubform.myText}}).

{{$formValid}}
Readonly boolean value containing whether the form has errors or is valid.
Some components provide more data that you can use, for example, $item and $searchText in the select component.

Workflow functions

There are some utility functions also available inside expressions. In the following examples we will use data from the payload below:

{
  order: [
    { name: "Macbook Pro", amount: 11,  price: 2631.32, category: "laptop" },
    { name: "Samsung 27''", amount: 4,   price: 304.12,  category: "peripheral" },
    { name: "Pack keyboard + mouse",  amount: 11,  price: 124.01,  category: "peripheral" }
  ],
  extraLines: [
    { name: "Handling", amount: 1,   price: 100.0,   category: "extra" },
    { name: "Shipping",  amount: 1,   price: 120.0,   category: "extra" }
  ]
}

List functions

Aggregation functions

Date functions

Mathematical functions

String functions

1. Format supports Moment.js string format. When it's not provided, it will use locale.timeFormat from translations file or HH:mm↩

2. Format supports Moment.js string format. When it's not provided, it will use locale.dateFormat from translations file or YYYY-MM-DD↩

3. Accepts locale, styles, fraction digits and currency options defined in the specification of the Intl.NumberFormat API.↩

Platform expressions

In Toqio Workflow Design, there are some additional expressions and static variables that can be used.

Exposed endpoints

In the form engine of Toqio Workflow Design, endpoints can be retrieved with the following expression: {{endpoints.xxx}}.

This variable is a dictionary object of the endpoints available to the forms inside expressions.

Current user

This expression is a new feature introduced in which you can retrieve the information of any user given its ID.

Internally, this makes an API call to retrieve the whole user object, so you can use any property inside the user retrieved. For example:

// Retrieve the user information for a given userId.
{{flw.getUser('myUserId').displayName}}

Under the hood, this expression is built with a performant cache, which means that if you call in the same page with the same expression and the same arguments, it will request the back end resource only a single time.

Usually, this concept is a common function to transform a userID to any other attribute of the user, e.g. the display name, when showing it into a data table row. Therefore, the data component section is filled with an htmlComponent. For example:

{
    "type": "htmlComponent",
    "value": "<span>{{flw.getUser($item.userId).displayName}}</span>"
}

Retrieve data object instances

This expression is a new feature that lets you retrieve the information of any data object instance:

// Retrieval of the data object instance based on dataObjectDefinitionKey, dataObjectOperationKey, dataObjectLookupKey and dataObjectLookupValue
{{flw.getDataObjectInstance('dataObjectDefinitionKey', 'dataObjectOperationKey', 'dataObjectLookupKey', 'dataObjectLookupValue').variableOne}}

Validation and validation errors

When called, this expression will trigger a validation of the component with the ID passed as a parameter (if undefined, it will trigger a validation of the entire form) and return an array of validation errors:

// validation triggered only for one component, where the id matches to 'componentId'
{{flw.validate('componentId')}}

// validation for the entire form
{{flw.validate()}} 

Custom validations

Custom validations let you make the form invalid when a condition is not met. You can apply custom validations to any component, and the error messages will be rendered close to it. Custom validations it's a list of validations. A validation has two parts:

• Expression: This expression returns a boolean. When the returned value is true, the validation is OK and no error will be shown.
• Error message: This message is shown to the user when the validation is not ok.

For example:

Or:

Please note that error messages are shown for a component only when the user has written the information inside it. Most times it means when the user focus left the input.

Ignore, visible, and enabled

• If visible is false or ignore is true, the component won't be rendered.
• If a component becomes ignored (its ignore attribute expression becomes true), the value the component is bound to will be deleted from the payload. If a container component becomes ignored, the values of its children will be deleted too.
• If the component is ignored or not enabled, the validations won't apply. And this component won't make form validations to fail.
• If the component is not enabled and not visible, the component won't be rendered or validated, and the value it's bound to won't be deleted from the payload.

Here’s a simple grid that lays out the information above:

Expression buttons (defining variables)

An expression button is a native button that allows the modeller to initiate or define variables and give dynamic logic to the form.

It stores the result of an expression:

• When you want to set a variable when the user clicks a button.
• When you want to set a variable when a panel is rendered, for example inside a wizard. To do that you can place the button inside a panel and set its visibility to false and auto execute to true.
• To have a "calculated variable" setting auto execute and timer.

Main attributes

Example

The following example shows a textfield that shows the value of a variable called times.

The logic of the form is to implement a counter.

The first button is an expression button that lets the user increase the counter when clicking.

The second button is a hidden expression button with autoexecute that initiates the variable to 0.

Expression button 1 configuration

Expression button 2 configuration (auto execute)

Changing the value of the variables, we can make a dynamic render based on the value of the variables by setting a conditional expression on the visible field of any component by clicking on the expression icon:

This is what the example will look like after clicking the button 10 times:

Buttons (navigation)

A button component is a simple button that redirects to a web location when clicked, with a hard refresh of the page.

Main attributes

Example

In this example, we will have two pages in an app.

By default, the app will render the first app located in the “Configure Pages” tab in Toqio Workflow Design.

A name for the path of the url of each page can be set and modified. The first page will be the one that is shown by default when the app gets rendered.

Let’s add a button to Page 1 that redirects to Page 2. Also, on Page 2, we can add a button to return to Page 1. To do that, we can use the base URL of the app that can be accessed by this expression: #/{{$route.currentAppId}}

This is how it looks in the E2E:

After selecting the button, we are redirected to Page 2:

The link component performs the same behaviour but with the aspect of a link instead of a button.

Rest button

A rest button is another type of button that lets us make queries to an HTTP endpoint and stores the response. You can use it to get values from the server manually or automatically. The main use of the rest button is for launching a process instance or querying a data object.

We can create a process instance by configuring the rest button as a post method, and requesting the process instance API: {{endpoints.process}}/runtime/process-instances

The result will be stored in the variable we set in the value property (variable expression) of the button accessing the path is configured in the response data path property (string).

In the send request attributes property, we can define the process we want to launch by adding the attribute “processDefinitionKey” and the value will be the key of the process we want to start.

We can also send a property called “variables” with a JSON in the values of the variables we want to send to the process in this format (name, type, value):

{{flw.JSON.parse(
'[{"name":"variable1","type":"string","value":"'+flw.JSON.stringify(var1)+'"}
,{"var2":"accessToken","type":"json","value":"'+var2+'"}]'
)
}}

We can configure the button with autoexecute as true so it will start a process when the form is rendered or based on conditions.

Main attributes

Example

For this example, we will configure a rest button as a process starter. To do this, we will set the method as a POST pointing to the process API URL.

We configure the process that will be started by adding the key of the process with the property “processDefinitioKey” as a send request attribute.

In the response, we will access the path variable to collect the variables of the process.

We can keep just the initiator variable by looking for it in the response by adding the find function in this value expression: {{flw.find($response, 'name', 'toqioInitiator').value}}.

The value of the response will be stored in the variable {{initiator}}.

We can define a custom data item component with the values FirstName, LastName, and Customer that will be retrieved from the response of the process call, and setting it’s visibility depending on the variable {{initiator}}, so it will be visible just when the button is clicked.

The result:

After selecting the button:

Subforms

Use a subform when you want to:

• Reuse components in different places.
• Organize code or components visually on the form/page design.
• Edit a list of elements of the same type (multiple entries set to true). This functions the same way as a forEach to display or render data based on a list.

Specific expressions

Main attributes

Example

In the following example, we will use a demo app called “Delivery App”.

This app is just a register form that also lets the user auto-generate the values of the form query using a random web API. There is a list of generated users where those users can be added or removed.

The list part of the form is built with a subform linked to the list of users, so every time the list increases, we will see the same thing that the list component sees.

This is how the form would look if the fields were to be modified:

We have configured a rest button that starts a process with the random icon. This process will call an API that generates random people. This data will be mapped with the properties of a “new Person item”.

We also have an expression button that adds the newPersonItem to the list of profiles:

We have created a simple form that contains a data item with the properties of the new person item values, and a separator.

This is the model form that we will use as a subform, so by linking the variable of the profiles to it we can render the subform based on each entry of the list (based on each person).

It winds up looking like this:

The variable must contain the same name as the properties of the parent variable as in this data example:

"profiles": [
    {
      "gender": "male",
      "name": {
        "title": "Mr",
        "first": "Héctor",
        "last": "Santana"
      },
      "location": {
        "street": {
          "number": 7575,
          "name": "Calle del Barquillo"
        },
        "city": "Cartagena",
        "state": "País Vasco",
        "country": "Spain",
        "postcode": 15847,
        "coordinates": {
          "latitude": "50.6963",
          "longitude": "-112.5687"
        },
        "timezone": {
          "offset": "0:00",
          "description": "Western Europe Time, London, Lisbon, Casablanca"
        }
      },
      "email": "[email protected]",
      "login": {
        "uuid": "7d7cc2e1-a3a5-495a-87f6-ecf5139238e7",
        "username": "yellowgorilla888",
        "password": "invest",
        "salt": "PmPvLuNq",
        "md5": "93ba714ddf556414bf6f2fe6d39676c4",
        "sha1": "c9c9231128b4adc2d5c7bf5c63daa76601e1d404",
        "sha256": "f5a56a9796f31e161e3543b3c0bf4831dacc9d650c890cdff42a3309d64f1c2d"
      },
      "dob": {
        "date": "1990-02-25",
        "age": 34
      },
      "registered": {
        "date": "2021-08-09T08:24:58.932Z",
        "age": 3
      },
      "phone": "901-512-594",
      "cell": "601-107-781",
      "id": {
        "name": "DNI",
        "value": "48991434-M"
      },
      "picture": {
        "large": "https://randomuser.me/api/portraits/men/31.jpg",
        "medium": "https://randomuser.me/api/portraits/med/men/31.jpg",
        "thumbnail": "https://randomuser.me/api/portraits/thumb/men/31.jpg"
      },
      "nat": "ES",
      "address": "Calle del Barquillo 7575, Cartagena"
    },
    {
      "gender": "female",
      "name": {
        "title": "Ms",
        "first": "Beatriz",
        "last": "Ramírez"
      },
      "location": {
        "street": {
          "number": 647,
          "name": "Calle de Arganzuela"
        },
        "city": "Parla",
        "state": "Galicia",
        "country": "Spain",
        "postcode": 42147,
        "coordinates": {
          "latitude": "18.2694",
          "longitude": "56.4883"
        },
        "timezone": {
          "offset": "-8:00",
          "description": "Pacific Time (US & Canada)"
        }
      },
      "email": "[email protected]",
      "login": {
        "uuid": "2bb215aa-5cfa-4ad7-9264-d868f6e4040e",
        "username": "crazysnake575",
        "password": "gustav",
        "salt": "V0NO2Cfj",
        "md5": "106d7d713ad91d5c84a3e9557c46076d",
        "sha1": "3f2cc08aa94eeaed3c6c0adf50ada8d153e99f83",
        "sha256": "6b438613ffc64124021af4a4e4d2080ebef2205a5f096c2f2f7bc1ad5787b1e8"
      },
      "dob": {
        "date": "1968-01-05",
        "age": 56
      },
      "registered": {
        "date": "2013-05-25T04:32:50.490Z",
        "age": 11
      },
      "phone": "938-202-095",
      "cell": "695-046-733",
      "id": {
        "name": "DNI",
        "value": "46161799-J"
      },
      "picture": {
        "large": "https://randomuser.me/api/portraits/women/92.jpg",
        "medium": "https://randomuser.me/api/portraits/med/women/92.jpg",
        "thumbnail": "https://randomuser.me/api/portraits/thumb/women/92.jpg"
      },
      "nat": "ES",
      "address": "Calle de Arganzuela 647, Parla"
    }
  ]

Lastly, we need to configure the subform with the variable that contains the list, {{profiles}}, with the multiple elements checkbox set to true, and the linked form reference:

This is how the app looks after calling the API several times to retrieve a random profile and adding them to the list: