Variables

To use variables, declare them in a separate variables block in the card root. When declaring a variable, specify the following parameters:

  • name: The name, can consist of Latin characters in different cases, digits, and _ and . symbols. It can't start with a digit or a dot.
  • type: The type of variable. See Data types.
  • value: The default value.

For example:

{
    "variables": [
        {
            "name": "subscribed",
            "type": "boolean",
            "value": true
        }
    ],
}
  1. Data types
  2. Non-local variables
  3. Changing the values of variables
  4. Running actions when changing variable values
  5. Learn more

Data types

Supported data types:
  • Boolean: boolean
  • String: string
  • Integer: integer
  • Floating-point number: number
  • Color: color
  • Link to the resource: url
Examples of declaring variables
{
    "variables": [
        {
            "name": "subscribed",
            "type": "boolean",
            "value": true
        },
        {
            "name": "likes",
            "type": "integer",
            "value": 0
        },
        {
            "name": "black",
            "type": "color",
            "value": "#f000"
        },
        {
            "name": "username",
            "type": "string",
            "value": "unknown"
        }
    ],
    "states": [ ... ]
}

Non-local variables

Variables declared in the card are considered local, and other cards don't have access to them. However, there may be cases when multiple cards must use one shared variable. In this case, it is acceptable to refer to undeclared variables. When trying to receive their values, the runtime environment can find these variables in DivContext if they are declared in it. In addition, the variables' values can be both read from the card and written in it.

Example of working with non-local variables on Android:
import com.yandex.div.data.Variable
...

val divContext: DivContext = provideYourDivContext()
divContext.divComponent.globalVariableController.putOrUpdate(
    Variable.StringVariable(name = "user_name", defaultValue = "undefined"),
    Variable.BooleanVariable(name = "dark_theme", defaultValue = true),
    ...
)

Changing the values of variables

To change the value of a variable declared in the card, the set_variable action can be used. For example:
div-action://set_variable?name=common_text_size&value=17

To set the value for a variable, you can use calculated expressions and built-in functions.

You can also change the values of variables using the SDK (in Android using DivView#setVariable ). The type of a new value must match the variable type, otherwise the value can't be applied.

Examples:

  • Change the value of a floating-point variable:
    div-action://set_variable?name=price&value=3.889
  • Change the value of a boolean variable:
    • true value: div-action://set_variable?name=is_liked&value=1
    • false value: div-action://set_variable?name=is_liked&value=0
  • Change the color type variable to green:
    div-action://set_variable?name=color_variable&value=@{encodeUri('#ff00ff00')}

Running actions when changing variable values

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 condition is checked:
    • on_condition: The action is triggered if the condition is met when a variable's value changes (the condition was not met before).
    • on_variable: The action is triggered each time the condition is met when the variable's value changes.
  • 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 is started every time the variables' values are changed and the condition is met.

Learn more

Follow DivKit news in the Telegram channel: http://t.me/divkit_news

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

DivKit Repository