PrizmDoc v12.4 - Updated
Mixin: Data

Mixin: Data

PCCViewer. Data

This object provides some helper methods that allow you to set and get data on any object.

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
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