Triggers

A trigger runs actions when the value of a variable changes and the specified condition is met. Triggers are declared at the card level and at the level of an individual element. All trigger parameters are listed in the reference.

Card triggers

When changing the variable value (except for updating all properties where the variable is used), any number of actions can be run. Add the trigger description in variable_triggers:

• condition: A condition for running the action. It can contain a boolean expression using variables or trigger events.

• mode: Determines when the action triggers:

  • on_condition: The action is triggered when a change in the variable results in a certain condition being met (the condition wasn't met until the action occurred).
  • on_variable: The action is triggered every time the condition is met when the value of the variable changes.

  For example, suppose the variables change several times, with condition returning true → true → false → true. When using on_condition, the action triggers two times, while with on_variable it triggers three times.

• actions: Describes actions that must be run when the condition is met.

Limitations:

• Conditions that don't contain variables (such as "condition": "@{1 == 1}") or contain functions that don't depend on variables won't work, because variables determine when to run the condition check.
• The trigger won't start if the compared entities in the condition have different types (for example, if a boolean variable is compared with an integer variable).

For example:

{
    "states": { ... },
    "variables": { ... },
    "variable_triggers": [
        {
            "condition": "@{liked}",
            "actions": [
                {
                    "url": "div-action://set_variable?name=total_likes&value=@{sum(total_likes, 1)}"
                }
            ]
        },
        {
            "condition": "@{subscribed && !liked}",
            "mode": "on_condition",
            "actions": [
                {
                    "url": "div-action://set_state?state_id=0/subscriptions/expanded"
                },
                {
                    "log_id": "common_posts_shown",
                    "url": "div-action://set_state?state_id=0/common_posts/collapsed"
                }
            ]
        },
        {
            "condition": "@{total_likes > 100 || user_name == 'John'}",
            "mode": "on_variable",
            "actions": [ ... ]
        }
  ]
}

In the example above, the first trigger runs the action that increases the total_likes variable value each time the liked variable value changes from false to true. The second trigger follows the same logic.

Because of the "mode": "on_variable" parameter, the third trigger fires every time the variable values are changed and the condition is met.

Element-level triggers

Element-level triggers are activated when the value of an element-level variable changes. Their format is the same as for card triggers.

An element-level trigger:

• has access to element-level variables of the parent object;

• is triggered even for invisible elements (with the parameter "visibility" = "gone"/"invisible");

• is not triggered in states and tabs that are not currently active;

• when used within item_builder prototypes, has access to the current item data through the variable specified in data_element_name and the current item index through the index variable.

When transitioning to a new state or another tab:

• if the state (tab) is activated for the first time, the trigger fires when the condition in condition is met;

• if the state (tab) has already been initialized and the condition was not met before exiting it, the trigger will fire when the condition starts to be met.

Learn more

You can discuss topics of interest in the DivKit user community in Telegram: https://t.me/divkit_community_en.

DivKit Repository