PrizmDoc v12.4 - Updated
Mixin: SessionData

Mixin: SessionData

PCCViewer. SessionData

This object provides some helper methods that allow you to set and get data on any object. In practice, any data saved using these methods will not be saved, it is purely for use during runtime.

Methods

getSessionData(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: While this is similar to PCCViewer.Data#getData, the data stored in the session will not persist when the page is reloaded, it is used for runtime operations.

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.setSessionData("Author", "Mark");

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

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

getSessionDataKeys() → {Array.<string>}

Gets an array of session data keys known to this object.

Note: While this is similar to PCCViewer.Data#getDataKeys, the data stored in the session will not persist when the page is reloaded, it is used for runtime operations.

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.getSessionDataKeys(); // returns []

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

setSessionData(key, value) → {object}

Sets the data value for the given key.

Note: While this is similar to PCCViewer.Data#setData, the data stored in the session will not persist when the page is reloaded, it is used for runtime operations.

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.getSessionData("Author"); // returns undefined

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

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

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

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