UIZE JavaScript Framework

MODULES Uize.Dom.Classes

SEARCHEXAMPLESSOURCETO DODEPSTEST

1. Introduction

The Uize.Dom.Classes module facilitates manipulation of the value of the className property of DOM nodes, with support for adding classes, removing classes, toggling classes, and more.

DEVELOPERS: Chris van Rensburg

1.1. Key Benefits

The Uize.Dom.Classes module provides a number of key benefits.

1.1.1. More Elegant, Easier to Read

It is certainly possible to manipulate classes using regular expressions, but the methods of the Uize.Dom.Classes module make it easier to do and make one's code easier to read.

1.1.1.1. An Example of Adding a Class

To illustrate the ease of use of the Uize.Dom.Classes module, consider the following example of adding a CSS class to a node's className property...

BEFORE

var node = Uize.Dom.Basics.getById ('recommendationsPod');
if (!/\bpodPopulated\b/.test (node.className)) {
  node.className += ' podPopulated';
}

AFTER

Uize.Dom.Classes.addClass ('recommendationsPod','podPopulated');

As you can see, the code using the Uize.Dom.Classes.addClass is much easier to read and understand.

1.1.1.2. An Example of Toggling a Class

In another illustration of the ease of use of the Uize.Dom.Classes module, consider the following example of toggling a CSS class in a node's className property...

BEFORE

var node = Uize.Dom.Basics.getById ('recommendationsPod');
if (/\bpodPopulated\b/.test (node.className)) {
  node.className = node.className.replace (/\bpodPopulated\b/,'');
} else {
  node.className += ' podPopulated';
}

AFTER

Uize.Dom.Classes.toggleClass ('recommendationsPod','podPopulated');

1.1.2. Powerful State Paradigm

In addition to ease of use, the Uize.Dom.Classes module introduces a powerful, higher level construct called a state.

The state related methods that support the state paradigm make it much easier to manage the classes in the className property of a node to reflect application state. Consider an example where you want the CSS class "selected" to be present in the className property of a node with the id of 'recommendationsPod' when the application variable podIsSelected is set to true, and to be absent when the variable is set to false. Your application will have updater code to update the className of the node to reflect the state of the podIsSelected variable. This updater code may not know or trust what the current state of the className property of the node might be, so it may test first to see if the "selected" class should be added or removed. You might write the code as follows...

BEFORE

if (podIsSelected) {
  Uize.Dom.Classes.addClass ('recommendationsPod','selected');
} else {
  Uize.Dom.Classes.removeClass ('recommendationsPod','selected');
}

Well, the Uize.Dom.Classes.setState static method makes this type of update operation a lot simpler. Instead of conditionally adding or removing the class, you simply set its state as follows...

AFTER

Uize.Dom.Classes.setState ('recommendationsPod','selected',podIsSelected);

This is a very simple use case, but the state related methods of the Uize.Dom.Classes module also support more sophisticated cases.

1.2. Adding a Class

A CSS class can be added to a node's className property using the Uize.Dom.Classes.addClass static method.

This method only adds the specified CSS class to the node's className property if the class isn't already present, so you will never have the same class occurring multiple times in the className as a result of calling this method.

The Uize.Dom.Classes.addClass method follows these basic rules...

1.   If the className property is empty, then it will be set to the class being added.
2.   If the class being added is already present in the className property, then the value of the className property will be unchanged (see important note on case sensitivity).
3.   If the class being added is not present but there are other classes in the className property, then the class being added will be appended, with a single space separating it from the other classes (if present).

To illustrate the above rules, consider the following example...

HTML - BEFORE

JAVASCRIPT

Uize.Dom.Classes.addClass (
  ['recommendationsPod','commentsPod','detailsPod'],
  'podPopulated'
);

HTML - AFTER

1.3. Removing a Class

A CSS class can be removed from a node's className property using the Uize.Dom.Classes.removeClass static method.

If the specified CSS class to remove isn't present in the node's className property, then calling this method will have no effect.

The Uize.Dom.Classes.removeClass method follows these basic rules...

1.   If the className property is empty, then it will simply remain empty.
2.   If the class being removed is present in the className property, then it will be removed along with any surrounding whitespace, while leaving the trailing whitespace if the class was between two surrounding classes (see important note on case sensitivity).
3.   If the class being removed is not present but there are other classes in the className property, then calling this method will have no effect.

To illustrate the above rules, consider the following example...

HTML - BEFORE

JAVASCRIPT

Uize.Dom.Classes.removeClass (
  ['recommendationsPod','commentsPod','detailsPod'],
  'selected'
);

HTML - AFTER

1.4. Toggling a Class

A CSS class can be toggled for a node's className property using the Uize.Dom.Classes.toggleClass static method.

The Uize.Dom.Classes.toggleClass method follows these basic rules...

1.   If the className property is empty, then it will be set to the class being toggled.
2.   If the class being toggled is not present in the node's className property, but there are other classes in the className property, then the class being toggled will be appended, with a single space separating it from the other classes (see important note on case sensitivity).
3.   If the class being toggled is present in the className property, then it will be removed along with any surrounding whitespace, while leaving the trailing whitespace if the class was between two surrounding classes (see important note on case sensitivity).

To illustrate the above rules, consider the following example...

HTML - BEFORE

JAVASCRIPT

Uize.Dom.Classes.toggleClass (['recommendationsPod','commentsPod'],'featured');

HTML - AFTER

1.5. Testing For a Class

The presence of a CSS class in a node's className property can be tested for by using the Uize.Dom.Classes.hasClass static method.

The Uize.Dom.Classes.hasClass method will return the value true if the class is present, and the value false if the class is not present (or if the specified node does not exist). When testing for the presence of a class, matching is case sensitive (see important note on case sensitivity)

EXAMPLE HTML

EXAMPLE JAVASCRIPT

var
  podIsSelected = Uize.Dom.Classes.hasClass ('recommendationsPod','selected'),
  podIsFeatured = Uize.Dom.Classes.hasClass ('recommendationsPod','featured')
;

In the above example, after the above JavaScript code has executed, the value of the podIsSelected variable will be false, and the value of the podIsFeatured variable will be true.

1.6. State Related Methods

Beyond simply adding, removing, and toggling CSS classes in the className property of nodes, the Uize.Dom.Classes module introduces a powerful, higher level construct called a state.

1.6.1. Presence or Absence State

Typically, when you're adding, removing, or toggling CSS classes for a DOM node, what you're really trying to do is have the node reflect some state in your application.

Often you will have a variable or a property of an object instance that will carry some important state, and you will want to update the className of a node (or multiple nodes) to reflect that state. Now, your code may not know or trust what the current state of the className property of a node might be, so it may test first to see if a class should be added or removed. You might write code as follows...

CONDITIONALIZED TOGGLE

if (podIsSelected != Uize.Dom.Classes.hasClass ('recommendationsPod','selected')) {
  Uize.Dom.Classes.toggleClass ('recommendationsPod','selected');
}

In the above example, whenever the value of the podIsSelected variable is true, then the CSS class called "selected" should be present in the node with the id of 'recommendationsPod'. When podIsSelected is false, then the "selected" class should be absent. In order to synchronize the DOM node's className property to correctly reflect the application state, some code must perform an update. In the update code, the code is first testing to see if the presence of the CSS class called "selected" does not match what the desired state should be. If it doesn't, then something must be done to make it match the desired state, so the CSS class is toggled (because its presence is the opposite of what it should be).

An alternative to the conditionalized toggling approach is a conditionalized add or remove approach, as shown below...

CONDITIONALIZED ADD OR REMOVE

if (podIsSelected) {
  Uize.Dom.Classes.addClass ('recommendationsPod','selected');
} else {
  Uize.Dom.Classes.removeClass ('recommendationsPod','selected');
}

Of course, you could get even more fancy with conditionalizing which static method to call, using a ternary operator, as follows...

FANCY CONDITIONALIZED ADD OR REMOVE

Uize.Dom.Classes [podIsSelected ? 'addClass' : 'removeClass'] (
  'recommendationsPod',
  'selected'
);

Well, whichever way you might write it, the Uize.Dom.Classes module reduces the above pattern to a more concise and conceptually elegant form with the help of the Uize.Dom.Classes.setState static method, as follows...

Uize.Dom.Classes.setState ('recommendationsPod','selected',podIsSelected);

The Uize.Dom.Classes.setState method takes three parameters: the node (or nodes) for which state should be set, the state class or classes (see Multiple State Classes), and the state value. In the above usage, calling the Uize.Dom.Classes.setState method will set the presence of the "selected" CSS class, based upon the value of the podIsSelected variable. If the value of podIsSelected is false, then the class will be removed. If the value of podIsSelected is true, then the class will be added.

1.6.2. Multiple State Classes

The state related methods become far more compelling and powerful when you consider their support for multiple state classes and what that means for managing CSS classes for DOM nodes.

In the simplest use of the Uize.Dom.Classes.setState method, the presence state of a single class can be controlled with a specified boolean value. This is in fact, however, a special case of a booean, two CSS class state where the first class (for the false value of the state) is an empty string and the second class (for the true value of the state) is the CSS class you specified. So, the following two statements are equivalent...

EQUIVALENT STATEMENTS

Uize.Dom.Classes.setState ('recommendationsPod','selected',podIsSelected);
Uize.Dom.Classes.setState ('recommendationsPod',['','selected'],podIsSelected);

So, what if a node should have one CSS class if a state's value is false, and a different CSS class if the state's value is true? This is accomplished quite easily. Consider an example where there is an enabled state variable in your application, whose value should be reflected in some node. When your enabled variable is false, then the node's className property should contain the CSS class "disabled". When your enabled variable is true, then the node's className property should contain the CSS class "enabled". Using the Uize.Dom.Classes.setState method's support for multiple state classes, the update code is made quite simple, as follows...

STATE UPDATE WITH TWO STATE CLASSES

Uize.Dom.Classes.setState ('recommendationsPod',['disabled','enabled'],enabled);

In the above statement, the value of the enabled variable is being passed as the state value in the call to the Uize.Dom.Classes.setState method. The false and true values of the state are mapped to the state classes 'disabled' and 'enabled'. For the state value false, the class 'disabled' should be present and the class 'enabled' should be absent. For the state value true, the opposite should be the case. The Uize.Dom.Classes.setState method does whatever is necessary to ensure that the correct state class is in the className property, removing and adding classes as needed. To perform this same kind of update without the Uize.Dom.Classes.setState method would be a little bit more laborious, as follows...

LABORIOUS APPROACH

if (enabled) {
  Uize.Dom.Classes.removeClass ('recommendationsPod','disabled');
  Uize.Dom.Classes.addClass ('recommendationsPod','enabled');
} else {
  Uize.Dom.Classes.removeClass ('recommendationsPod','enabled');
  Uize.Dom.Classes.addClass ('recommendationsPod','disabled');
}

You could reduce the above code down using some fancy tricks and avoid using the Uize.Dom.Classes.setState method, but the Uize.Dom.Classes.setState method makes things more semantically elegant.

1.6.2.1. More Than Two State Classes

The state related methods become even more compelling when you consider their support for more than two state classes.

There may be situations where a state is not binary, and having two CSS classes mapped to the state will not suffice. Consider the example where a DOM node may need to be styled to reflect an error level, where the first error level is no error, the second level is a non-critical warning type error, and the third level is a critical, fatal, or blocking error. In this situation, your application may have a state variable called errorLevel, whose value can be 0, 1, or 2, and where the value 0 should be mapped to the state class '' (empty string), the value 1 should be mapped to the state class 'warning', and the value 2 should be mapped to the state class 'error'.

Fortunately, the state related methods support multiple state classes specified in array form. So, our updater code would look as follows...

STATE UPDATE WITH THREE STATE CLASSES

Uize.Dom.Classes.setState ('recommendationsPod',['','warning','error'],errorLevel);

In another three state classes example, consider a text input element whose className property should contain a CSS class to reflect the validation status of the text entered by the user. The three levels for validation state are: 1) the text has not yet been validated, 2) the text has been validated and has failed validation, and 3) the text has been validated and has passed validation. The application may have a validationStatus variable, where the value 0 indicates not yet validated, the value -1 indicates failed validation, and the value 1 indicates passed validation. We want the value 0 to map to the state class '' (empty string), the value -1 to map to the state class valueBad, and the value 1 to map to the state class valueGood. Our updater code would look as follows...

STATE UPDATE WITH STATE VALUE OFFSET

Uize.Dom.Classes.setState ('phone',['valueBad','','valueGood'],validationStatus + 1);

Notice how we are adding 1 to the value of the validationStatus variable when calling the Uize.Dom.Classes.setState method and how the empty string state class is now in the middle of the state classes array.

1.6.3. Setting State

State can be reflected with CSS classes in the className property of one or more DOM nodes using the Uize.Dom.Classes.setState static method.

EXAMPLE

Uize.Dom.Classes.setState ('recommendationsPod',['disabled','enabled'],enabled);

In the above example, the value of the enabled variable will determine whether the CSS class 'enabled' or the CSS class 'disabled' will be present in the className property of the node with the id of 'recommendationsPod'. If the value of the enabled variable is false, then the 'enabled' class will be removed and the 'disabled' class will be added. Conversely, if the value of the enabled variable is true, then the 'disabled' class will be removed and the 'enabled' class will be added.

The Uize.Dom.Classes.setState method, along with the other state related methods, supports multiple state classes.

1.6.4. Getting State

As with setting state for CSS classes using the Uize.Dom.Classes.setState static method, the current value for a state can be determined from the className property of a node using the Uize.Dom.Classes.getState static method.

EXAMPLE

var enabled = Uize.Dom.Classes.getState ('recommendationsPod',['disabled','enabled']);

In the above example, the value of the enabled variable will be determined by whether the CSS class 'enabled' or the CSS class 'disabled' is present in the className property of the node with the id of 'recommendationsPod'. If the className property contains the class 'disabled', then the enabled variable will be set to false. Conversely, if the className property contains the class 'enabled', then the enabled variable will be set to true.

The Uize.Dom.Classes.getState method, along with the other state related methods, supports multiple state classes.

1.6.5. Toggling State

State that is reflected with CSS classes in the className property of one or more DOM nodes can be toggled (or cycled, for more than two state classes) using the Uize.Dom.Classes.toggleState static method.

EXAMPLE

Uize.Dom.Classes.toggleState ('recommendationsPod',['disabled','enabled']);

In the above example, whichever of the two CSS classes 'disabled' or 'enabled' is present in the className property of the node with the id of 'recommendationsPod' will be replaced with the other. So, if the className property contains the class 'disabled', then it will be replaced with the class 'enabled'. Conversely, if the className property contains the class 'disabled', then it will be replaced with the class 'enabled'. If the className property contains neither of the classes 'disabled' or 'enabled', then the first of the state classes (i.e. 'disabled') will be added.

The Uize.Dom.Classes.toggleState method, along with the other state related methods, supports multiple state classes.

1.6.5.1. Toggling State With More Than Two State Classes

When a state is represented by more than two state classes, then the Uize.Dom.Classes.toggleState method will cycle through the state classes.

When cycling through multiple state classes, the Uize.Dom.Classes.toggleState method follows these basic rules...

1.   If none of the state classes are present in the node's className property, then the first of the state classes will be appended, with a single space separating it from the other classes (if present).
2.   If any of the state classes other than the last of the state classes is present in the node's className property, then it will be replaced with the next state class in the list.
3.   If the last of the state classes is present in the node's className property, then it will be replaced with the first state class in the list (i.e. wrapping around).

To illustrate the above rules, consider the following example...

HTML - BEFORE

JAVASCRIPT

Uize.Dom.Classes.toggleState (['input1','input2','input3'],['','warning','error']);

HTML - AFTER

1.6.6. Removing State

State classes associated with a state can be removed from the className property of one or more DOM nodes using the Uize.Dom.Classes.removeState static method.

Removing a state is distinct from setting state and toggling state - removing a state for a node makes it so that the state no longer applies for that node. When removing a state, the Uize.Dom.Classes.removeState method follows these basic rules...

1.   If the className property is empty, then it will simply remain empty.
2.   If the className property is not empty, but none of the state classes for the state being removed are present, then the className property will remain unchanged.
3.   If one of the state classes for the state being removed is present in the className property, then it will be removed along with any surrounding whitespace, while leaving the trailing whitespace if the class was between two surrounding classes.

To illustrate the above rules, consider the following example...

HTML - BEFORE

JAVASCRIPT

Uize.Dom.Classes.removeState (['input1','input2','input3'],['','warning','error']);

HTML - AFTER

The Uize.Dom.Classes.removeState method, along with the other state related methods, supports multiple state classes.

1.7. Important Considerations

When working with CSS classes using the methods of the Uize.Dom.Classes module, there are some important considerations to keep in mind.

1.7.1. Case Sensitivity

When matching CSS classes against the value of a node's className property, the methods of the Uize.Dom.Classes module perform case sensitive matching.

To illustrate this, consider the following example...

HTML - BEFORE

JAVASCRIPT

Uize.Dom.Classes.addClass ('recommendationsPod','selected');
Uize.Dom.Classes.removeClass ('commentsPod','selected');
Uize.Dom.Classes.toggleClass ('detailsPod','selected');

HTML - AFTER

This case sensitivity rule applies equally to the state related methods.

1.7.2. Whitespace Handling

When adding, replacing, or removing classes from the className property of a node, the methods of the Uize.Dom.Classes module observe certain principles regarding whitespace.

1.7.2.1. Minimal Whitespace Added When Adding Classes

When a class needs to be added by a Uize.Dom.Classes method, it will be appended to the className property, with a single space separating it from the other classes (if present).

1.7.2.2. Whitespace Respected When Replacing Classes

When replacing classes in the className property of a node, the methods of the Uize.Dom.Classes module will respect existing whitespace separating classes.

This means that if a class is separated from surrounding classes by tabs, newlines, or multiple spaces, then that whitespace separation will be retained when the class is replaced with a different class. The exception to this rule is where the new class is the empty string (see No Whitespace Bloat When Removing Classes).

1.7.2.3. No Whitespace Bloat When Removing Classes

In the case where a class is being removed by one of the Uize.Dom.Classes methods and the class is surrounded by other classes, the trailing whitespace that separates the class being removed from the next class will be retained, while the whitespace that separates it from the previous class will be lost.

This behavior avoids whitespace bloat that might otherwise occur if all surrounding whitespace were retained when classes are repeatedly removed and added for a node.

1.8. Examples

There are no dedicated showcase example pages for the Uize.Dom.Classes module.

SEARCH FOR EXAMPLES

Use the link below to search for example pages on the UIZE Web site that reference the Uize.Dom.Classes module...

SEARCH

1.9. Implementation Info

The Uize.Dom.Classes module defines the Uize.Dom.Classes package under the Uize.Dom namespace.

1.9.1. Features Introduced in This Module

The features listed in this section have been introduced in this module.

STATIC METHODS

Uize.Dom.Classes.addClass | Uize.Dom.Classes.getState | Uize.Dom.Classes.hasClass | Uize.Dom.Classes.removeClass | Uize.Dom.Classes.removeState | Uize.Dom.Classes.setState | Uize.Dom.Classes.toggleClass | Uize.Dom.Classes.toggleState

STATIC PROPERTIES

Uize.Dom.Classes.moduleName | Uize.Dom.Classes.pathToResources

1.9.2. Features Overridden in This Module

No features have been overridden in this module.

1.9.3. Features Inherited From Other Modules

This module has no inherited features.

1.9.4. Modules Directly Under This Namespace

There are no modules directly under this namespace.

1.9.5. Unit Tests

The Uize.Dom.Classes module is unit tested by the Uize.Test.Uize.Dom.Classes test module.

2. Static Methods

2.1. Uize.Dom.Classes.addClass

Adds the specified CSS class to the className property of the specified node(s), provided that the class name is not already present.

SYNTAX

Uize.Dom.Classes.addClass (nodeBLOB,classSTR);

For a more detailed discussion and to see examples, see the section Adding a Class.

NOTES

see the companion Uize.Dom.Classes.removeClass static method
see the related Uize.Dom.Classes.hasClass and Uize.Dom.Classes.toggleClass static methods
see also the Uize.Dom.Classes.setState static method

IMPLEMENTATION INFO

this feature was introduced in this module

2.2. Uize.Dom.Classes.getState

Returns a boolean or integer (a value of the type stateBOOLorINT), indicating the current state for the specified state classes.

SYNTAX

stateBOOLorINT = Uize.Dom.Classes.getState (nodeSTRorOBJ,stateClassesSTRorARRAY);

For a more detailed discussion and to see examples, see the section Getting State.

NOTES

see the companion Uize.Dom.Classes.setState, Uize.Dom.Classes.toggleState, and Uize.Dom.Classes.removeState static methods

IMPLEMENTATION INFO

this feature was introduced in this module

2.3. Uize.Dom.Classes.hasClass

Returns a boolean, indicating whether or not the specified node's className property contains the specified CSS class.

SYNTAX

hasClassBOOL = Uize.Dom.Classes.hasClass (nodeSTRorOBJ,classSTR);

For a more detailed discussion and to see examples, see the section Testing For a Class.

NOTES

see the related Uize.Dom.Classes.addClass, Uize.Dom.Classes.toggleClass, and Uize.Dom.Classes.removeClass static methods
see also the Uize.Dom.Classes.getState static method

IMPLEMENTATION INFO

this feature was introduced in this module

2.4. Uize.Dom.Classes.removeClass

Removes the specified CSS class from the className property of the specified node(s), provided that the class is present.

SYNTAX

Uize.Dom.Classes.removeClass (nodeBLOB,classSTR);

For a more detailed discussion and to see examples, see the section Removing a Class.

NOTES

see the companion Uize.Dom.Classes.addClass static method
see the related Uize.Dom.Classes.hasClass and Uize.Dom.Classes.toggleClass static methods
see also the Uize.Dom.Classes.setState static method

IMPLEMENTATION INFO

this feature was introduced in this module

2.5. Uize.Dom.Classes.removeState

Updates the className property of the specified node(s), to no longer contain one of the specified state classes.

SYNTAX

Uize.Dom.Classes.removeState (nodeBLOB,stateClassesSTRorARRAY);

For a more detailed discussion and to see examples, see the section Removing State.

NOTES

see the companion Uize.Dom.Classes.getState, Uize.Dom.Classes.setState, and Uize.Dom.Classes.toggleState static methods

IMPLEMENTATION INFO

this feature was introduced in this module

2.6. Uize.Dom.Classes.setState

Updates the className property of the specified node(s), to contain the one CSS class out of the specified state classes that corresponds to the specified state.

SYNTAX

Uize.Dom.Classes.setState (nodeBLOB,stateClassesSTRorARRAY,stateBOOLorINT);

For a more detailed discussion and to see examples, see the section Setting State.

NOTES

see the companion Uize.Dom.Classes.getState, Uize.Dom.Classes.toggleState, and Uize.Dom.Classes.removeState static methods

IMPLEMENTATION INFO

this feature was introduced in this module

2.7. Uize.Dom.Classes.toggleClass

Toggles the presence of the specified CSS class in the className property of the specified node(s).

SYNTAX

Uize.Dom.Classes.toggleClass (nodeBLOB,classSTR);

For a more detailed discussion and to see examples, see the section Toggling a Class.

NOTES

see the related Uize.Dom.Classes.addClass, Uize.Dom.Classes.hasClass, and Uize.Dom.Classes.removeClass static methods
see the related Uize.Dom.Classes.toggleState static method

IMPLEMENTATION INFO

this feature was introduced in this module

2.8. Uize.Dom.Classes.toggleState

Updates the className property of the specified node(s), to contain the one CSS class out of the specified state classes that corresponds to the state that is obtained from the specified node(s) and then advanced by one.

SYNTAX

Uize.Dom.Classes.toggleState (nodeBLOB,stateClassesSTRorARRAY);

For a more detailed discussion and to see examples, see the section Toggling State.

NOTES

see the companion Uize.Dom.Classes.getState and Uize.Dom.Classes.setState static methods
see the related Uize.Dom.Classes.toggleClass static method

IMPLEMENTATION INFO

this feature was introduced in this module

3. Value Types

For the sake of not redundantly describing the value types for certain method parameters and return values repeatedly, some common value types are described here.

3.1. classSTR

A string, specifying the name of a single CSS class.

A classSTR value should be a valid CSS class name for a single class - it may not be a space separated list of multiple classes. Values of this type can be accepted by the Uize.Dom.Classes.hasClass, Uize.Dom.Classes.addClass, Uize.Dom.Classes.removeClass, and Uize.Dom.Classes.toggleClass static methods.

3.2. stateBOOLorINT

A boolean or integer, specifying a state that maps to one of the CSS classes specified in a stateClassesSTRorARRAY value.

Values of this type can be accepted by the Uize.Dom.Classes.setState static method. Values of this type are returned by the Uize.Dom.Classes.getState static method. When a stateBOOLorINT value is specified along with a stateClassesSTRorARRAY value when calling the Uize.Dom.Classes.setState method, it can be a boolean or an integer, where the boolean value false is equivalent to the integer value 0, and where the boolean value true is equivalent to the integer value 1. The stateClassesSTRorARRAY value should not exceed the number of classes specified in a stateClassesSTRorARRAY value. If it does, then it will be "wrapped" around to become a value that is within range.

3.3. stateClassesSTRorARRAY

A comma-separated string or an array of strings, specifying a list of CSS classes that are to be mapped to a stateBOOLorINT type value.

Values of this type can be accepted by the state related methods (Uize.Dom.Classes.setState, Uize.Dom.Classes.getState, Uize.Dom.Classes.toggleState, and Uize.Dom.Classes.removeState). A stateClassesSTRorARRAY value should generally specify two or more state classes, typically specifying just two (e.g. 'disabled,enabled' or ['disabled','enabled']).

In the special case where only one state class is specified (e.g. 'enabled' or ['enabled']), it is implicit that the class specified is the second of two state classes where the first class is an empty string. Therefore, the string value 'enabled' and the array value ['enabled'] would be equivalent to the values ',enabled' and ['','enabled'], respectively. This behavior provides a convenient shorthand for simple presence or absence state cases, where a specified single CSS class is to be mapped to the true value of a binary state (such as an enabled or selected state, for example), and where the false value is represented by the absence of that class.

4. Static Properties

4.1. Uize.Dom.Classes.moduleName

IMPLEMENTATION INFO

this feature was introduced in this module

4.2. Uize.Dom.Classes.pathToResources

IMPLEMENTATION INFO

this feature was introduced in this module