View Source Luminous.Variable behaviour (luminous v2.6.1)
A variable is defined inside a Dashboard and its values are determined at runtime. The variable also stores a current value that can be updated. A variable value can be simple (just a value) or descriptive in that it contains a label (for display purposes) and the actual value.
Variables are visualized as dropdowns in the dashboard view.
There are two Variable types:
single: only one value can be selected by the user (default type)multi: multiple values can be selected by the user
A Variable can also be hidden in which case:
- it will not be rendered as a dropdown in the dashboard
- it will not be included in the URL params
Hidden variables are a means for keeping some kind of state for framework clients. A typical use case is implementing custom panels which need some state (e.g. pagination).
Link to this section Summary
Callbacks
A module must implement this behaviour to be passed as an argument to define!/1.
The function receives the variable id and the LV socket assigns.
Functions
Defines a new variable and returns a map. The following options can be passed
Extract and return the value from the descriptive variable value.
Find and return the variable with the specified id in the supplied variables.
Returns the variable's current (descriptive) value(s) or nil.
Find the variable with the supplied id in the supplied variables
and return its current extracted value.
Returns the label based on the variable type and current value selection
Uses the callback to populate the variables's values and returns the updated variable. Additionally, it sets the current value to be the first of the available values in the case of a single variable or all of the available values in the case of a multi variable.
Replaces the variables current value with the new value and returns the map. It performs a check whether the supplied value is a valid value (i.e. exists in values). If it's not, then it returns the map unchanged. The special "none" case is for when the variable's type is :multi and none of the values are selected (empty list)
Link to this section Types
Link to this section Callbacks
@callback variable(atom(), map()) :: [simple_value() | descriptive_value()]
A module must implement this behaviour to be passed as an argument to define!/1.
The function receives the variable id and the LV socket assigns.
Link to this section Functions
Defines a new variable and returns a map. The following options can be passed:
:id(atom/0) - Required.:label(String.t/0) - Required.:module(atom/0) - Required.:type- The default value is:single.:hidden(boolean/0) - The default value isfalse.
@spec extract_value(descriptive_value()) :: binary() | [binary()] | nil
Extract and return the value from the descriptive variable value.
Find and return the variable with the specified id in the supplied variables.
@spec get_current(t()) :: descriptive_value() | [descriptive_value()] | nil
Returns the variable's current (descriptive) value(s) or nil.
Find the variable with the supplied id in the supplied variables
and return its current extracted value.
Returns the label based on the variable type and current value selection
Uses the callback to populate the variables's values and returns the updated variable. Additionally, it sets the current value to be the first of the available values in the case of a single variable or all of the available values in the case of a multi variable.
Replaces the variables current value with the new value and returns the map. It performs a check whether the supplied value is a valid value (i.e. exists in values). If it's not, then it returns the map unchanged. The special "none" case is for when the variable's type is :multi and none of the values are selected (empty list)