There are no tracking or monitoring cookies on this site. There are only cookies used for documentation examples related to cookies.Close
Processing...
This may take a few seconds.

Regular variables

Variables in Active CSS are different to CSS variables. You cannot use CSS variables in Active CSS.

You are not allowed to put HTML into regular variables for reasons to do with XSS. If you want to place HTML into variables for rendering, you should use HTML variables.

Variable scopes

There are 3 types of variable scopes used in Active CSS.

1. The document scope. All Active CSS variables are automatically in the document scope, unless they are inside a private component area.

2. The private component scope. This refers to Active CSS variables only. The private component scope is always underneath a top-level component host element, and the scope refers to all non-private components beneath it in the element tree. You specify if a component is a private component by using "private" in the @component declaration.

3. Private JavaScript function scope. All JavaScript functions have a self-contained scope. You can access window-scoped variables outside of Active CSS from within the function. It's the same scope that you would normally find in a JavaScript function.

Active CSS variables are not easily available in JavaScript from the window scope. They are internal to Active CSS, and are only available for use in JavaScript functions within the config if you specifically request them to be with the "vars" command.

Declaring or changing a variable

To set up a variable, you use the "var" command. You use "var" if you are declaring it in the document scope or a shadow DOM scope. Both scopes use the same methods of using variables. You can use the same variable name in different scopes and they won't clash.

You can set up variables for strings, booleans (true/false), numbers, arrays or JavaScript objects, like you would in JavaScript. The syntax for writing the variable's value is the same as JavaScript, but the command to declare the variable looks a bit different to fall in line with CSS.

In fact, the right-hand side can be any JavaScript expression that translates to a string, boolean (true/false), number, array or a JavaScript object.

For example:

var: player "X";

This sets up a variable called "player", and gives it a value of "X".

It is the equivalent of this in JavaScript:

var player = "X";

The reason we didn't do this syntax: 'player: "X";' is because variable names could end up clashing with command names. So this syntax was a compromise. Having this syntax for the var command allows us to not have to worry about prefixes for variables anywhere else in the config. It's arguably a cleaner look to not have to use prefixes on variables, such as "$myvar", and looks less messy when the variable is referenced in JavaScript code. Additionally, CSS variables have a prefix of "--" which is no good to us, as "--" is an operator in JavaScript and would be confusing, because we need to reference the variables in JavaScript expressions. As the variables themselves can be used in JavaScript expressions, having "--" as a prefix wouldn't work as "--" is a maths operator. So for consistency within a JavaScript context, there is no prefix at all. This "var" command solution gives us therefore more simplicity than the CSS method. CSS variables are great in a stylesheet context, but they are not compatible with JavaScript. Here we can use the same variable names in Active CSS within JavaScript and perform all the mathematical and functional uses that JavaScript provides.

Displaying the value of a variable

To use a variable in an action command (or a target selector or conditional command) you put it in "curlies" (technical term), like this:

render: "{player}";

Above, the variable name is player, and you use the curlies when you want to access it from within regular config commands. This tells the core "we need to substitute the value of 'player' into here and draw it". If you are referencing the variable directly in the var command or in JavaScript, you don't use curlies.

Data-binding a variable

To data-bind an Active CSS variable, all you do is put it in "double-curlies" where are drawing the variable, like this:

render: "The player is: {{player}}";

Only the contents in double-curlies will automatically update - the surrounding text will not be affected.

You can also data-bind elements in arrays and also object references:

render: "{{myObject.mySubObject.ref}} {{myArray[0]}}";

This means that whenever the variable changes in memory, it will also change wherever you have data-bound it on the page. There are examples of this in the examples section of this site. You can only data-bind variables declared as Active CSS variables, so only variables declared with "var" or mentioned with "vars" inside JavaScript (see below for using Active CSS variables in JavaScript).

It's a one-way data-binding method. If you are thinking about putting data-binding for use in a form, you might find the "mimic-into" command more useful than data-binding, as it has form-binding built-in which clears target areas on reset so you don't have to worry about changing variable values if the form is reset.

Data-binding can be an odd technique to program with if you are not used to it, but it can make certain things simple to code once you get your head around it.

With data-binding you can just set the variable and forget about it, which is great - you just change the variable and it will change the display. It can be useful in SPAs to update areas of the page that change as you navigate the website. You could also tie in a variable contained in a class attribute, so that CSS changes in certain scenarios. It's a cool thing if you can find a reason to use it and have some fun with it, but you can work around and find an alternative method of doing something if you don't like the idea of data-binding.

Declaring an Active CSS variable inside JavaScript

You can also declare an Active CSS variable inside a JavaScript function in the config. You cannot declare a variable in a JavaScript expression, as an expression is not a function. An expression is merely the right-hand side of an equation, like where "a = c + d", "c + d" is called the "expression". A function would be a list of JavaScript commands that do stuff.

You would also declare an Active CSS variable inside JavaScript when you wanted to use the variable elsewhere, outside of the function, or perhaps in a different JavaScript snippet somewhere else, while remaining in the Active CSS config.

To do this, there is a special Active CSS command that you can use inside JavaScript, the "vars" command.

So, when using Active CSS variables in native JavaScript in "run", "create-command", etc., you need to use the "vars" command to make the Active CSS variable or variables available for use inside the JavaScript function. Otherwise, they will appear as undefined in the function.

For example, you are on a broccoli diet, and want to remind yourself of this every time you click on a button, and you want to use run:

body:init {
run: {=
// This is all pure native JavaScript, except the special Active CSS "vars" command.
vars food, nowFood;
food = ['broccoli', 'cheese', 'tofu', 'chicken'];
nowFood = food[0]; // You are on a broccoli diet.
=};
}

button:click {
#myPTag {
render: "I like {food[1]} and {food[2]}, and also {food[3]}, but what I am having today is {nowFood}.";
}
}

In the example above, you can use {food[1]} outside the run function in the config because you declared it with "vars" inside JavaScript. You could of course have done this whole thing in the config without resorting to run, like this:

body:init {
var: food ['broccoli', 'cheese', 'tofu', 'chicken'],
nowFood food[0];
}

button:click {
#myPTag {
render: "I like {food[1]} and {food[2]}, and also {food[3]}, but what I am having today is {nowFood}.";
}
}