persistence: The ContextHub.Utils.Persistence object for this store. The default value is the ContextHub.persistence object.

isEventingPaused()

Determines whether eventing is paused for this store.

Returns

A boolean value:

true
: Eventing is paused so that no events are triggered for this store.

false
: Eventing is not paused so that events are triggered for this store.

pauseEventing()

Pauses eventing for the store so that no events are triggered. This function requires no parameters and returns no value.

removeItem(key, options)

Removes a key/value pair from the store.

When a key is removed, the function triggers the
data
event. The event data includes the store name, the name of the key that was removed, the value that was removed, new value for the key (null), and the action type of "remove".

Optionally, you can prevent the triggering of the
data
event.

Parameters

key:
(String) The name of the key to remove.

options:
(Object) An object of options. The following object properties are valid:

silent: A value of
true
prevents the triggering of the
data
event. The default value is
false
.

Returns

A
boolean
value:

A value of
true
indicates the key/value pair was removed.

A value of
false
indicates that the data store is unchanged because the key was not found in the store.

removeReference(key)

Removes a reference from the store.

Parameters

key:
The key reference to remove. This parameter corresponds with the
key
parameter of the
addReference
function.

Returns

A
boolean
value:

A value of
true
indicates the reference was removed.

A value of
false
indicates that the key was not valid and the store is unchanged.

reset(keepRemainingData)

Resets the initial values of the store's persisted data. Optionally, you can remove all other data from the store. Eventing is paused for this store while the store is reset. This function returns no value.

Initial values are provided in the initialValues property of the config object that is used to instantiate the store object.

Parameters

keepRemainingData:
(Boolean) A value of true causes non-initial data to be persisted. A value of false causes all data to be removed except for the initial values.

Resets the initial values of the store's persisted data. Optionally, you can remove all other data from the store. Eventing is paused for this store while the store is reset. This function returns no value.

Initial values are provided in the initialValues property of the config object that is used to instantiate the store object.

Parameters

keepRemainingData: (Boolean) A value of true causes non-initial data to be persisted. A value of false causes all data to be removed except for the initial values.

resolveReference(key, retry)

Retrieves a referenced key. Optionally, you can specify the number of iterations to use for resolving the best match.

Parameters

key:
(String) The key for which to resolve the reference. This
key
parameter corresponds with the
key
parameter of the
addReference
function.

retry:
(Number) The number of iterations to use.

Returns

A
string
value that represents the referenced key. If no reference is resolved, the value of the
key
parameter is returned.

resumeEventing()

Resumes eventing for this store so that events are triggered. This function defines no parameters and returns no value.

setItem(key, value, options)

Adds a key/value pair to the store.

Triggers the
data
event only if the value for the key is different than the value that is currently stored for the key. You can optionally prevent the triggering of the
data
event.

The event data includes the store name, the key, the previous value, the new value, and the action type of
set
.

Parameters

key:
(String) The name of the key.

options:
(Object) An object of options. The following object properties are valid:

silent: A value of
true
prevents the triggering of the
data
event. The default value is
false
.

value:
(Object) The value to associate with the key.

Returns

A
boolean
value:

A value of
true
indicates the data object was stored.

A value of
false
indicates that the data store is unchanged.

ContextHub.Store.JSONPStore

A store that contains JSON data. The data is retrieved from an external JSONP service, or optionally from a service that returns JSON data. Specify the service details using the
init
function when you create an instance of this class.

The store uses in-memory persistance (Javascript variable). Store data is available only during the lifetime of the page.

Functions (ContextHub.Store.JSONPStore)

configureService(serviceConfig, override)

Configures the details for connecting to the JSONP service that this object uses. You can either update or replace the existing configuration. The function returns no value.

Parameters

serviceConfig:
An object that contains the following properties:

host: (String) The server name or IP address.

jsonp: (Boolean) A value of true indicates that the service is a JSONP service, false otherwise. When true, the {callback: "ContextHub.Callbacks.
Object.name
} object is added to the service.params object.

secure: (String or Boolean) Determines the protocol to use for the service URL:

auto: //

true: https://

false: https://

override:
(Boolean). A value of
true
causes the existing service configuration to be replaced by the properties of
serviceConfig
. A value of
false
causes the existing service configuration properties to be merged with the properties of
serviceConfig
.

getRawResponse()

Returns the raw response that is cached since the last call to the JSONP service. The function requires no parameters.

Returns

An object that represents the raw response.

getServiceDetails()

Retrieves the service object for this ContextHub.Store.JSONPStore object. The service object contains all of the information required to create the service URL.

Returns

An object with the following properties:

host:
(String) The server name or IP address.

jsonp:
(Boolean) A value of true indicates that the service is a JSONP service, false otherwise. When true, the {callback: "ContextHub.Callbacks.
Object.name
} object is added to the service.params object.

secure: (String or Boolean) Determines the protocol to use for the service URL:

auto: //

true: https://

false: https://

timeout: (Number) The amount of time to wait for the JSONP service to respond before timing out, in milliseconds.

ttl: The minimum amount of time in milliseconds that passes between calls to the JSONP service. (See the
queryService
function).

queryService(reload)

Queries the remote JSONP service and caches the response. If the amount of time since the previous call to this function is less than the value of
config.service.ttl
, the service is not called and the cached response is not changed. Optionally, you can force the service to be called. The
config.service.ttl
property is set when calling the
init
function to initialize the store.

Triggers the ready event when the query is finished. If the JSONP service URL is not set, the function does nothing.

Parameters

reload:
(Boolean) A value of true removes the cached response and forces the JSONP service to be called.

reset

Resets the initial values of the store's persisted data and then calls the JSONP service. Optionally, you can remove all other data from the store. Eventing is paused for this store while the initial values are reset. This function returns no value.

Initial values are provided in the initialValues property of the config object that is used to instantiate the store object.

Parameters

keepRemainingData:
(Boolean) A value of true causes non-initial data to be persisted. A value of false causes all data to be removed except for the initial values.

resolveParameter(f)

Resolves the given parameter.

ContextHub.Store.PersistedJSONPStore

ContextHub.Store.PersistedJSONPStore extends
ContextHub.Store.JSONPStore
so it inherits all of the functions of that class. However, the data that is retrieved from the JSONP service is persisted according to the configuration of ContextHub persistence. (See
Persistence Modes
.)

ContextHub.Store.PersistedStore

ContextHub.Store.PersistedStore extends
ContextHub.Store.Core
so it inherits all of the functions of that class. The data in this store is persisted according to the configuration of ContextHub persistence.

ContextHub.Store.SessionStore

ContextHub.Store.SessionStore extends
ContextHub.Store.Core
so it inherits all of the functions of that class. The data in this store is persisted using in-memory persistance (Javascript object).

getAllItems(filter)

(Optional)
filter:
Criteria for matching cookie keys. To return all cookies, specify no value. The following types are supported:

String: The string is compared to the cookie key.

Array: Each item in the array is a filter.

A RegExp object: The test function of the object is used to match cookie keys.

A function: A function that tests a cookie key for a match. The function must take the cookie key as a paramter and return true if the test confirms a match.

Returns

An object of cookies. Object properties are cookie keys and key values are cookie values.

Example

ContextHub.Utils.Cookie.getAllItems([/^cq-authoring/, /^cq-editor/])

getItem(key)

Returns a cookie value.

Parameters

key:
The key of the cookie for which you want the value.

Returns

The cookie value, or
null
if no cookie was found for the key.

Example

ContextHub.Utils.Cookie.getItem("name");

getKeys(filter)

Returns an array of the keys of existing cookies that match a filter.

Parameters

filter:
Criteria for matching cookie keys. The following types are supported:

String: The string is compared to the cookie key.

Array: Each item in the array is a filter.

A RegExp object: The test function of the object is used to match cookie keys.

A function: A function that tests a cookie key for a match. The function must take the cookie key as a paramter and return
true
if the test confirms a match.

Returns

An array of strings where each string is the key of a cookie that matches the filter.

Example

ContextHub.Utils.Cookie.getKeys([/^cq-authoring/, /^cq-editor/])

removeItem(key, options)

Removes a cookie. To remove the cookie, the value is set to an emtpy string and the expiry date is set to the day before the current date.

Parameters

key:
A
String
value that represents the key of the cookie to remove.

options:
An object that contains property values for configuring the cookie attributes. See the
[setItem](/help/sites-developing/contexthub-api.md#setitem-key-value-options)
function for information. The
expires
property has no effect.

Returns

This function does not return a value.

Example

ContextHub.Utils.Cookie.vanish([/^cq-authoring/, 'cq-scrollpos']);

setItem(key, value, options)

Creates a cookie of the given key and value, and adds the cookie to the current document. Optionally, you can specify options that configure the attributes of the cookie.

Parameters

key:
A String that contains the key of the cookie.

value:
A String that contains the cookie value.

options:
(Optional) An object that contains any of the following properties that configure the cookie attributes:

expires: A
date
or
number
value that specifies when the cookie expires. A date value specifies the absolute time of expiry. A number (in days) sets the time of expiry to the current time plus the number. The default value is
undefined
.

secure: A
boolean
value that specifies the
Secure
attribute of the cookie. The default value is
false
.

path: A
String
value to use as the
Path
attribute of the cookie. The default value is
undefined
.

selector:
(String) A unique identifier for the bind. You need the selector to identify the bind if you want to use the
off
function to remove the bind.

triggerForPastEvents:
(Boolean) Indicates whether the handler should be executed for events that occurred in the past. A value of
true
calls the handler for past events. A value of
false
calls the hander for future events. The default value is
true
.

Returns

When the
triggerForPastEvents
argument is
true
, this function returns a
boolean
value that indicates whether the event occurred in the past:

true
: The event occurred in the past and the handler will be called.

false
: The event has not occurred in the past.

If
triggerForPastEvents
is
false
, this function returns no value.

Example

The following example binds a function to the data event of the geolocation store. The function populates an element on the page with the value for the latitude data item from the store.

once(name, handler, selector, triggerForPastEvents)

Binds a function to an event. The function is called only once, for the first occurrence of the event. Optionally, the function can be called for the event that has occurred in the past, before the binding is established.

selector:
(String) A unique identifier for the bind. You need the selector to identify the bind if you want to use the
off
function to remove the bind.

triggerForPastEvents:
(Boolean) Indicates whether the handler should be executed for events that occurred in the past. A value of
true
calls the handler for past events. A value of
false
calls the hander for future events. The default value is
true
.

Returns

When the
triggerForPastEvents
argument is
true
, this function returns a
boolean
value that indicates whether the event occurred in the past:

true
: The event occurred in the past and the handler will be called.

false
: The event has not occurred in the past.

If
triggerForPastEvents
is
false
, this function returns no value.

ContextHub.Utils.inheritance

A utility class that enables an object to inherit the properties and methods of another object.

Functions (ContextHub.Utils.inheritance)

inherit(child, parent)

Causes an object to inherit the properties and methods of another object.

Parameters

child:
(Object) The object that inherits.

parent:
(Object) The object that defines the properties and methods that are inherited.

ContextHub.Utils.JSON.tree

This class facilitates the manipulation of data objects that to be stored or are retrieved from ContextHub stores.

Functions (ContextHub.Utils.JSON.tree)

addAllItems()

Creates a copy of a data object and adds to it the data tree from a second object. The function returns the copy and does not modify either of the original objects. When the data trees of the two objects contain identical keys, the value of the second object overwrites the value of the first object.

Parameters

tree:
The object that is copied.

secondTree:
The object that is merged with the copy of the
tree
object.

Returns

An object that contains the merged data.

cleanup()

Creates a copy of an object, finds and removes items in the data tree that contain no values, null values, or undefined values, and returns the copy.

Parameters

tree:
The object to clean.

Returns

A copy of tree that is cleaned.

getItem()

Retrieves the value from an object for the a key.

Parameters

tree:
The data object.

key:
The key for the value that you want to retrieve.

Returns

The value that corresonds with the key. When the key has child keys, this function returns a complex object. When the type of the value for the key is
undefined
,
null
is returned.

sanitizeKey(key)

Sanitizes string values to make them usable as keys. To sanitize a string, this function performs the following actions:

Reduces multiple consecutive forward slashes to a single slash.

Removes whitespace from the beginning and ending of the string.

Splits the result into an array of strings that are demarcated by slashes.

Use the resultant array to create a usable key.
Parameters

key:
The
string
to sanitize.

Returns

An array of
string
values where each string is the portion of the
key
that was demarcated by slashes. represents the sanitized key. If the sanitized array has a length of zero, this function returns
null
.

Example

The following code sanitizes a string to produce the array
["this", "is", "a", "path"]
, and then generates the key
"/this/is/a/path"
from the array:

setItem(tree, key, value)

Adds a key/value pair to the data tree of a copy of an object. For information about data trees, see
Persistence
.

Parameters

tree: A data object.

key: The key to associate with the value that you are adding. The key is the path to the item in the data tree. This function calls
ContextHub.Utils.JSON.tree.sanitize
to sanitize the key before adding it.

registerStoreCandidate(store, storeType, priority, applies)

Registers a store object as a store candidate using a name and priority.

The priority is a number that indicates the importance of same-named stores. When a store candidate is registered using the same name as an already-registered store candidate, the candidate with the higher priority is used. When registering a store candidate, the store is registered only if the priority is higher than same-named registered store candidates.

Parameters

store:
(Object) The store object to register as a store candidate.

storeType:
(String) The name of the store candidate. This value is required when creating an instance of the store candidate.

priority:
(Number) The priority of the store candidate.

applies:
(Function) The function to invoke that evaluates the applcability of the store in the current environment. The function must return
true
if the store is applicable, and
false
otherwise. The default value is a function that returns true:
function() {return true;}