var

Syntax

var: (name) (value/expression) [session-storage|local-storage] [every (time)] [after (time)][, (name)...];

/* As of version 2.11.0, use the syntax below for regular variables. */

$name: (value/expression) [session-storage|local-storage] [every (time)] [after (time)][, (name)...];

name = The name of the variable to declare or re-assign. Use this when setting window variables, like "window.something".

$name = The name of the variable to declare or re-assign. This is the preferred method for regular variables because the dollar variable syntax can handle more scenarios.

value/expression = The value of the variable. This is written in native JavaScript and must be a JavaScript expression.

session-storage = optional - only use this option when the variable is first declared - this also places the regular variable into session storage (see this page for more details of what session storage is: https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage). Whenever the regular variable changes, it automatically updates in session storage too. Think of session storage as the place where the variable lives. It can be used as a reactive variable too.

local-storage = optional - only use this option when the variable is first declared - this also places the regular variable into local storage (see this page for more details of what local storage is: https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage). Whenever the regular variable changes, it automatically updates in local storage too. Think of local storage as the place where the variable lives. It can be used as a reactive variable too.

 

The value can be a JavaScript string, number, boolean (true or false), array or object.

JavaScript expressions in the variable value can just be written as straight JavaScript.

Make sure that if you are assigning anything to a variable that converts to a string, such as {@data-myString}, that it is always wrapped in quotes, otherwise it will fail the JavaScript expression evaluation! (eg. var: "{@data-myString}";)

Examples:

$player "X";
$gameState: ['', '', '', '', '', '', '', '', ''];
$roundWon: false;
$roundDraw: false;
$bondFilm: "mostly all of them";
$a: $b;
$a[0]: { name: "Dave" };
$a[0].name: "Cheryl";
$date: new Date().toLocaleTimeString();
$anAttr: "{@data-something}";   /* <-- see the quotes - an attribute is _not_ a variable */
$player: ($player == 'X') ? 'O' : 'X';
$winners: [
        [0, 1, 2],
        [3, 4, 5],
        [6, 7, 8],
        [0, 3, 6],
        [1, 4, 7],
        [2, 5, 8],
        [0, 4, 8],
        [2, 4, 6]
    ];

/* When used inside quotes, action commands, target selectors and CSS, variables need to be converted to a string first, like this:
render: "{$aStringVar}";
background-color: {$aColor};
add-class: .{$prefix}Color;
#{@data-id} {
    ...
}
.aBeginning{$someClassBit}AnEnding {
    ...
}

Using ++ or --

Instead of this:

$count: 0;
$count: $count + 1;
$count: $count - 1;

You can do this:

$count: 0;
$count++;
$count--;

See the Regular variables page for more information on their use.

A note on local-storage and session-storage

If a variable is referenced (eg. render: "{myVariable}") but hasn't been declared in ACSS with the var command, then local and session storage will be scanned automatically and if the variable is there then it will be grabbed from there for use. It will then be used like a regular variable, and will automatically be updated in local or session storage. That will be where the variable "lives".

To stop this automatic behaviour, simply declare the variable before use with the var command, but without local-storage or session-storage options.

But it isn't very difficult to use. If it's in local or session storage, you don't need to do anything other than just use it like a regular variable. If you need to declare it as a local or session storage right at the beginning, use the local-storage or session-storage options.

If you need to check whether or not it exists before you freshly declare it, you can do something like this, which declares the variables for local storage, but only if it can't be found anyway (remember - ACSS will look in local storage or session storage and use it from there if it can):

body:not-if-defined($myString):preInit {
    $myString: "starting value" local-storage;
}

body:not-if-defined($myObject):preInit {
    $myObject: {} local-storage; 
}