Mixin: Data

Methods

getData(key) → {string|object}

Gets the data value for the given key, or gets a hash containing all key values, if a key was not provided.

Note: If a hash is returned, this will be a new object each time it is called. Adding new properties to the returned hash will not add data to the object.

Note: The returned data is not mutated or sanitized, which could lead to a security vulnerability if not sanitized properly before use.

Parameters:

Name	Type	Description
`key`	string	The key for which to get the data value.

See:

Throws:

If the key argument is null or otherwise not a string.

Type: Error

Returns:

If a key argument was provided, it returns the associated value.
If a key argument was provided, but a value has not been associated with the key, then it returns undefined.
If a key was not provided, it returns a hash object containing all key-value pairs.

Type: string | object

Example

// The key "Author" is set the value "Mark".
item.setData("Author", "Mark");

// The key "Note" is set the value "This is really important!".
item.setData("Note", "This is really important!");

item.getData("Author"); // returns "Mark"
item.getData();         // returns {"Author":"Mark", "Note":"This is really important!"}
item.getData("FooBar"); // returns undefined

getDataKeys() → {Array.<string>}

Gets an array of data keys known to this object.

See:

Returns:

Returns an array of data keys known to this object. If no data is stored, then an empty array will be returned.

Type: Array.<string>

Example

// Returns an empty array before KVPs are stored.
item.getDataKeys(); // returns []

// Returns a list of all keys.
item.setData("Author", "Mark");
item.setData("Note", "This is really important!");
item.getDataKeys(); // returns ["Author", "Note"]

setData(key, value) → {object}

Sets the data value for the given key.

Notes:

Overwrites any data value already associated with the given key.
There is no artificial limit imposed on the number of key-value pairs that are stored.
If limits on the number of KVPs are required, they should be enforced by calling code.
Setting the value as undefined results in no information for the key being persisted to the server.
The returned data is not mutated or sanitized, which could lead to a security vulnerability if not sanitized properly before use.

Parameters:

Name Type Description

Name	Type	Description
`key`	string	The key for which to set the data value.
`value`	string	This is the value to set for the key. This must be a string or undefined. The maximum length of the string is not limited by this function.

key

string

The key for which to set the data value.

value

string

This is the value to set for the key.

This must be a string or undefined.
The maximum length of the string is not limited by this function.

See:

Returns:

The object on which the method was called.

Type: object

Example

// Get data returns undefined before the key is set.
item.getData("Author"); // returns undefined

// The key "Author" is set the value "Mark".
item.setData("Author", "Mark");
item.getData("Author"); // returns "Mark"

// The key "Author" is overwritten with the value "Clark".
item.setData("Author", "Clark");
item.getData("Author"); // returns "Clark"

// The key "Author" is unset, by setting the value to undefined.
item.setData("Author", undefined);
item.getData("Author"); // returns undefined

// The value can only be set to a string or undefined.
// All other data types throw.
item.setData("FooBar", null); // throws
item.setData("FooBar", 1);    // throws
item.setData("FooBar", true); // throws
item.setData("FooBar", {});   // throws
item.setData("FooBar", []);   // throws