Actions

Action elements add dynamic functionality to app forms. For example, they may call api methods, go to another form or manipulate form data. Actions may be attached to form buttons (form actions), table options (context menu), events etc.

Here is the list of different action types. Use the type link to read more about it.

Common properties

The following properites are common for all action types:

Method - run an API method action

Use this type of action to run an api method. The following properties define a method action:

• “method” - the name of the method to call
• “params” - method input parameters (optional). When not provided, the list of parameters will be automatically collected according to the method’s metadata.
• “data” - assignment instructions for recevied data (optional). When not provided, the form will be automatically populated with received data
• “onOK” - an action to run after this one completes successfully (optional)
• “onError” - an action to run when this one fails (optional)

Let’s assume, that we have an api method salesOrder.get that takes orderNumber as input parameter and returns information about this order.

Single method call with auto parameters

The method will be called with input parameter orderNumber taken from the matching (by name) form field.

{ "method": "salesOrder.get" }

The received data will be processed automatically - all matching fields will be populated with the field data from the response.

Single method call with manually provided parameters

The method will be called with input parameter orderNumber taken from form field orderNr.

{ 
    "method": "salesOrder.get",
    "params": {
        "orderNumber": "orderNr"
    }
}

Chain of method calls using onOK

In this example, after a successfull call of salesOrder.get, next one will be called customerInfo.get and after that one - addresses.get. The parameters will be automatically processed and passed to each method. For example, if salesrder.get returns field customerNumber it may be used in other methods in the chain (passed automatically according to method’s metadata). You may override it by using params property when needed. In case of error, onError action will be called. In this case another form errorHandling will be displayed.

{
    "method": "salesOrder.get", 
    "onOK": {
        "method": "customerInfo.get",
        "onOK": { "method": "addresses.get" }
    },
    "onError": {
        "form": "errorHandling"
    }
}

Received data assignments

To manually handle received data, use data property and specify assignment instructions. This way you can map response values to different form fields. Sometimes it is necessary when dealing with two or more methods that return the same fields, for instance, 2 tables (“items”, “items2”); then you can use assignment: { “items2”: “items”} for one of the methods.

In this example, form field custNr will get the value of customerNumber data field from the response. You may add assignments for multiple fields returned in the response.

{ 
    "method": "salesOrder.get",
    "data": {
        "custNr": "customerNumber"
    }
}

Form - go to a form action

This type of action is used to display (go to) another form. The action is defined by the following properties:

• “form” - the name of the form to display. There are some predefined form names that may be used:
  • *back - go back to previous form
  • *close - close current form
• “params” - the list of form input parameters (optional). When not provided, the list of parameters will be automatically collected according to the destination form declaration.
• “target” - this property gives more control over form stack (optional). One of the predefined values may be used:
  • new - clear the stack and open the form as the first one
  • first - go back to the first form found on the stack with given name
  • last - go back to the last (previous) form found on the stack with given name

By default, forms are put on a stack when swithcing between them. For example, if you start with form A and then go to form B, C and A, the stack will contain forms: A->B->C->A. So, it is possible to go back to previous forms by using predefined *back action. To have more control over which form to go to see target property.

Form actions example

{
    "title": "MyForm"
    
    "actions": [
        "*close",
        {
            "form": "*back",
            "text": "Previous"
        },
        { 
            "text": "Adresses",
            "form": "address",
            "params": {
                "customerNumber": "custNr"
            }
        },
        { 
            "text": "Sales orders",
            "form": "salesOrders",
            "target": "last"
        }
    ]
}

There are 4 form actions specified in the example above:

• *close - closes the form
• *back - goes to previous form (note a custom action text)
• Addresses - goes to form address passing customerNumber as input parameter taken from custNr field
• Sales orders - goes back to previous salesOrders form

Conditional statements

A conditional statement is a control flow statement. It tells your script to run different actions depending on boolean result of a test specified in “if” part.

Properties:

• “if”: “expression-string” - expression is a simple test to evaluate a boolean result. Examples:
  • “quantity > 5” - tests if field quantity has value greater than 5
  • “orderActive” - tests if field orderActive is true (boolean type)
• “then”: then-action - run then-action when the test expression evaluates to true
• “else”: else-action - run else-action when the test expression evaluates to false (optional)
• “always”: always-action - run always-action after the if-then-else statement irrespective of if test result (optional).

Example

{
    "if": "linesExist",
    "then": { "method": "myMethod.run" },
    "else": {
        "if": "salesOrderStatus == 'active' && salesOrderPrice < 100",
        "then": { "method": "myMethod2.run" }
    },
    "always": {
        "form": "*back"
    }
}

This is an illustrative conditional action. After one of then/else actions has been completed (depending on the value of linesExist) the program will go to the previous form (always action).

Set - assigment instructions

Use this action to assing values to fields. The body of the action contains a list of assignment statements to execute. The left-hand side of each statement is always a destination field name. The right hand-side may be one of the following:

• field name
• literal (number, boolean, single quated string)
• expression

Example of various assignment instructions

{
    "set": {
        "myValueFromField": "orderNr",
        "myText": "'Text line 1'",
        "myNumber": 123,
        "myBoolean": true,
        "myValueFromExpr": "counter + 1"
    }
}

In the example above, the values from the right-hand side of the statements will be assigned to my* fields/variables.

You may provide set instructions inside another type of action. The assignments will be executed first - before the hosting action.

Example of running a method action with assignment instructions

{ 
    "set": { "counter": "counter + 1" },
    "method": "salesOrder.get"
}

In this case, the counter variable will be increased each time before salesOrder.get is called.

Focus - set focus on a field

When you need to give focus to an input field, use the following action syntax:

“focus”: “field-name” - where field-name is the id of the field to receive focus.

You may use focus instruction inside another type of action.

Example of setting focus to orderNumber field

{ 
    "focus": "orderNumber"
}

For each - a loop statement

For each loop action will iterate over given array of elements and execute specified inner action for each element of the array. By default, the input array is the selected rows of the parent table. If ‘array’ property is provided it will be used as the input array. Inside ‘forEach’ action you can refer to fields of currently being processed item by preceding the field name with ‘#’.

Properties:

• foreach - action to be executed for each element of the array
• array - the name of the variable holding a list of elements (optional). If not provided, the parent table element will be used. Use doulbe hash ‘##’ before the name to get only the selected rows of the table.
• onOK - action to run on loop completion (optional)

Example of iterating over table items

{ 
    "text": "Delete",
    "array": "##items", 
    "forEach": {
        "set": { "sum" : "sum + #price" },
        "method": "item.delete",
        "params": {
            "item": "#itemID"
        }
    }, 
    "onOK": { 
        "form": "presentResult"
    }
}

For each selected element of items, the action will run set instruction and then call API method item.delete providing item id as input parameter. When the loop completes, the program will open presentResult form.