Skip to content

Latest commit

 

History

History
210 lines (136 loc) · 9.57 KB

dataset.md

File metadata and controls

210 lines (136 loc) · 9.57 KB
Raw

Classes

Dataset

Dataset objects allow to do typical CRUD operations on an element's data attributes, with support for a namespace

Functions

dataset(element, [ns]) ⇒ Dataset

Returns a Dataset object for a given element and namespace, using a cache to avoid unnecessary object creation (when called with the same element and namespace, it will always return the same object)


Dataset

Dataset objects allow to do typical CRUD operations on an element's data attributes, with support for a namespace


new Dataset(element, [ns])

Creates an instance of Dataset

Param Type Description
element Element the element for which we are creating the instance
[ns] string optional namespace. If specified, it will be put at the beginning of every class name set through this class. If not specified, a global one previously set will be used.


dataset.has(name) ⇒ boolean

Gives true if the data attribute with the given name (after applying an eventual namespace) exists on the element

Param Type Description
name string the name of the attribute. It accept names expressed also in camelCase, it will internally be converted to proper data attribute name.


dataset.get([name], [fallbackValue]) ⇒ string | number | boolean | Array | object | null

Retrieve a data attribute value or all of them as long as they match the previously set namespace. Returned values are casted to the proper type among boolean, numbers, array and object (when they are encoded as JSON)

Returns: string | number | boolean | Array | object | null - the retrieved value or values after casting them in the proper type or the fallbackValue

Param Type Description
[name] string, object When a string value is passed, it returns the the value of that attribute after applying the namespace. Name passed in camelCase are supported. If the attribute is not set it returns the eventual fallbackValue passed as a second parameter, or null otherwise. When no value is passed, it returns all data attributes values that match with the set namespace. When a plain object is passed, it is used as a set of default values: in will return all the values that match the namespace when they are available or the given default values
[fallbackValue] * When a string name is passed and that attribute is not present, this fallbackValue will be returned


dataset.getString([name], [fallbackValue]) ⇒ string | object | null

Exactly like the get() method, but without casting the value types, they will be returned as string

Returns: string | object | null - the retrieved value or values as strings or the fallbackValue.

Param Type Description
[name] string, object @see get() method
[fallbackValue] * get() method


dataset.set(name, [value])

Sets one or more data attributes values, after applying the namespace to their name. Plain objects and arrays are stored in their JSON representation

Param Type Description
name string, object the name of the data attribute to be set or a plain object containing multiple name-value entries to be set. The names can be expressed in camelCase and the eventual namespace will be added before setting them
[value] string, number, boolean, Array, object, null The value to be set when the name is a string


dataset.remove(name)

Remove a data attribute, after applying the eventual namespace to the name

Param Type Description
name string the name of the attribute to be removed. Can be expressed in camelCase format.


Dataset.encode(value) ⇒ string

Cast values to strings. Used before storing the values in the data attributes

Returns: string - the string representation of the given value

Param Type Description
value string, number, boolean, Array, object, null the value to be cast


Dataset.decode(value) ⇒ string | number | boolean | Array | object | null

Try to cast a value expressed as string to a more suitable standard type

Returns: string | number | boolean | Array | object | null - The value after the cast

Param Type Description
value string the string value to be converted


dataset(element, [ns]) ⇒ Dataset

Returns a Dataset object for a given element and namespace, using a cache to avoid unnecessary object creation (when called with the same element and namespace, it will always return the same object)

Returns: Dataset - a Dataset object for the given element and namespace

Param Type Description
element Element the element for which we are creating the instance
[ns] string optional namespace. If specified, it will be put at the beginning of every data attribute name set through the class. If not specified, a global one previously set will be used.


dataset.getNs() ⇒ string

Gets the global namespace


dataset.setNs(value)

Sets the global namespace

Param Type Description
value string the new namespace


dataset.selector(name, [value], [ns]) ⇒ string

Returns a CSS selector in the form [data-ns-name] or [data-ns-name="value"] for the given attribute name and value, taking into account the namespace.

Returns: string - the generated CSS selector

Param Type Description
name string data attribute name for the selector. It accepts also names in camelCase
[value] string, number, boolean, Array, object, null the optional value to be used in the selector, to generate a form . It gets converted to string
[ns] string optional namespace. If specified, it will be put at the beginning of the data attribute name class name. If not specified, a global one previously set will be used.


dataset.attrName(name, [value], [ns]) ⇒ string

Returns a data attribute name for the given name, taking into account the namespace.

Returns: string - the generated attribute name in the form data-ns-name

Param Type Description
name string accepts also names in camelCase
[value] string, number, boolean, Array, object, null the optional value to be used in the selector, to generate a form . It gets converted to string.
[ns] string optional namespace. If specified, it will be put at the beginning of the data attribute name. If not specified, a global one previously set will be used.