ContextHub JavaScript API Reference contexthub-javascript-api-reference

The ContextHub JavaScript API is available to your scripts when the ContextHub component has been added to the page.

ContextHub Constants contexthub-constants

Constant values that the ContextHub JavaScript API defines.

Event Constants event-constants

The following table lists the names events that occur for ContextHub Stores. See also ContextHub.Utils.Eventing.

UI Event Constants ui-event-constants

The following table lists the names of events that occur for the ContextHub UI.

ContextHub JavaScript API Reference contexthub-javascript-api-reference-2

The ContextHub object provides access to all stores.

Functions (ContextHub) functions-contexthub

getAllStores() getallstores

Returns all registered ContextHub stores.

This function has no parameters.

Returns returns-

An object that contains all ContextHub stores. Each store is an object that uses the same name as the store.

Example example-

The following example retrieves all stores and then retrieves the geolocation store:

var allStores = ContextHub.getAllStores();
var geoloc = allStores.geolocation

getStore(name) getstore-name

Retrieves a store as a JavaScript object.

Parameters parameters-

Returns returns-getstore-name

An object that represents the store.

Example example-getstore-name

The following example retrieves the geolocation store:

var geoloc = ContextHub.getStore("geolocation");

ContextHub.SegmentEngine.Segment contexthub-segmentengine-segment

Represents a ContextHub segment. Use the ContextHub.SegmentEngine.SegmentManager to obtain segments.

Functions (ContextHub.ContextEngine.Segment) functions-contexthub-contextengine-segment

getName() getname

Returns the name of the segment as a String value.

getPath() getpath

Returns the repository path of the segment definition as a String value.

ContextHub.SegmentEngine.SegmentManager contexthub-segmentengine-segmentmanager

Provides access to ContextHub segments.

Functions (ContextHub.SegmentEngine.SegmentManager) functions-contexthub-segmentengine-segmentmanager

getResolvedSegments() getresolvedsegments

Returns the segments that are resolved in the current context. This function has no parameters.

Returns returns-getresolvedsegments

An array of ContextHub.SegmentEngine.Segment objects.

ContextHub.Store.Core contexthub-store-core

The base class for ContextHub stores.

Properties (ContextHub.Store.Core) properties-contexthub-store-core

eventing eventing

A ContextHub.Utils.Eventing object. Use this object for binding functions to store events. For information about the default value and initialization, see init(name,config).

name name

The name of the store.

persistence persistence

A ContextHub.Utils.Persistence object. For information about the default value and initialization, see init(name,config).

Functions (ContextHub.Store.Core) functions-contexthub-store-core

addAllItems(tree, options) addallitems-tree-options

Merges a data object or an array with the store data. Each key/value pair in the object or array is added to the store (via the setItem function):

Values can be objects.

Parameters parameters-addallitems

Returns returns-addallitems

A boolean value:

addReference(key, anotherKey) addreference-key-anotherkey

Creates a reference from one key to another key. A key cannot reference itself.

Parameters parameters-addreference

Returns returns-addreference

A boolean value:

announceReadiness() announcereadiness

Triggers the ready event for this store. This function has no parameters and returns no value.

clean() clean

Removes all data from the store. The function has no parameters and no return value.

getItem(key) getitem-key

Returns the value that is associated with a key.

Parameters parameters-getitem

Returns returns-getitem

An Object that represents the value for the key.

getKeys(includeInternals) getkeys-includeinternals

Retrieves the keys from the store. Optionally you can retrieve the keys that are used internally by the ContextHub framework.

Parameters parameters-getkeys

Returns returns-getkeys

An array of key names ( string values).

getReferences() getreferences

Retrieves the references from the store.

Returns returns-getreferences

An array that uses referencing keys as indices for the referenced keys:

getTree(includeInternals) gettree-includeinternals

Retrieves the data tree from the store. Optionally you can include the key/value pairs that are use internally by the ContextHub framework.

Parameters parameters-gettree

Returns returns-gettree

An object that represents the data tree. The keys are the property names of the object.

init(name, config) init-name-config

Initializes the store.

Parameters parameters-init

isEventingPaused() iseventingpaused

Determines whether eventing is paused for this store.

Returns returns-iseventingpaused

A boolean value:

pauseEventing() pauseeventing

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

removeItem(key, options) 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 parameters-removeitem

Returns returns-removeitem

A boolean value:

removeReference(key) removereference-key

Removes a reference from the store.

Parameters parameters-removereference

Returns returns-removereference

A boolean value:

reset(keepRemainingData) 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 parameters-reset

resolveReference(key, retry) resolvereference-key-retry

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

Parameters parameters-resolvereference

Returns returns-resolvereference

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

resumeEventing() resumeeventing

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

setItem(key, value, options) 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 from 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 parameters-setitem

Returns returns-setitem

A boolean value:

ContextHub.Store.JSONPStore 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.

ContextHub.Store.JSONPStore extends ContextHub.Store.Core and inherits the functions of that class.

Functions (ContextHub.Store.JSONPStore) functions-contexthub-store-jsonpstore

configureService(serviceConfig, override) 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 parameters-configureservice

getRawResponse() getrawresponse

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

Returns returns-getrawresponse

An object that represents the raw response.

getServiceDetails() getservicedetails

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

Returns returns-getservicedetails

An object with the following properties:

getServiceURL(resolve) getserviceurl-resolve

Retrieves the URL of the JSONP service.

Parameters parameters-getserviceurl

Returns returns-getserviceurl

A string value that represents the service URL.

init(name, config) init-name-config-1

initializes the ContextHub.Store.JSONPStore object.

Parameters parameters-init-1

queryService(reload) 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.ttlproperty 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 parameters-queryservice

reset 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 parameters-reset-1

resolveParameter(f) resolveparameter-f

Resolves the given parameter.

ContextHub.Store.PersistedJSONPStore contexthub-store-persistedjsonpstore

ContextHub.Store.PersistedJSONPStore extends ContextHub.Store.JSONPStore so it inherits all 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

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

ContextHub.Store.SessionStore contexthub-store-sessionstore

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

ContextHub.UI contexthub-ui

Manages UI modules and UI module renderers.

Functions (ContextHub.UI) functions-contexthub-ui

registerRenderer(moduleType, renderer, dontRender) registerrenderer-moduletype-renderer-dontrender

Registers a UI module renderer with ContextHub. After the renderer is registered, it can be used to create UI modules. Use this function when you are extending ContextHub.UI.BaseModuleRenderer to create a custom UI Module renderer.

Parameters parameters-registerrenderer

Example example-registerrenderer

The following example registers a renderer as the contexthub.browserinfo module type.

ContextHub.UI.registerRenderer('contexthub.browserinfo', new SurferinfoRenderer());

ContextHub.Utils.Cookie contexthub-utils-cookie

A utility class for interacting with cookies.

Functions (ContextHub.Utils.Cookie) functions-contexthub-utils-cookie

exists(key) exists-key

Determines whether a cookie exists.

Parameters parameters-exists

Returns returns-exists

A boolean value of true indicates that the cookie exists.

Example example-exists

if (ContextHub.Utils.Cookie.exists("name")) {
   // conditionally-executed code
}

getAllItems(filter) getallitems-filter

Returns all cookies that have keys that match a filter.

Parameters parameters-getallitems

Returns returns-getallitems

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

Example example-getallitems

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

getItem(key) getitem-key-1

Returns a cookie value.

Parameters parameters-getitem-1

Returns returns-getitem-1

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

Example example-getitem-1

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

getKeys(filter) getkeys-filter

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

Parameters parameters-getkeys-1

Returns returns-getkeys-1

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

Example example-getkeys-1

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

removeItem(key, options) removeitem-key-options-1

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

Parameters parameters-removeitem-1

Returns returns-removeitem-1

This function does not return a value.

Example example-removeitem-1

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

setItem(key, value, options) setitem-key-value-options-1

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 parameters-setitem-1

Returns returns-setitem-1

The cookie with the set value.

Example example-setitem-1

ContextHub.Utils.Cookie.setItem("name", "mycookie", {
    expires: 3,
    domain: 'localhost',
    path: '/some/directory',
    secure: true
});

vanish(filter, options) vanish-filter-options

Removes all cookies that match a given filter. Cookies are matched using the getKeys function and removed using the removeItem function.

Parameters parameters-vanish

Returns returns-vanish

This function does not return a value.

ContextHub.Utils.Eventing contexthub-utils-eventing

Enables you to bind and unbind functions to ContextHub store events. Access ContextHub.Utils.Eventing objects for a store using the eventing property of the store.

Functions (ContextHub.Utils.Eventing) functions-contexthub-utils-eventing

off(name, selector) off-name-selector

Unbinds a function from an event.

Parameters parameters-off

Returns returns-off

This function returns no value.

on(name, handler, selector, triggerForPastEvents) on-name-handler-selector-triggerforpastevents

Binds a function to an event. The function is called every time the event occurs. Optionally, the function can be called for events that have occurred in the past, before the binding is established.

Parameters parameters-on

Returns returns-on

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

If triggerForPastEvents is false, this function returns no value.

Example example-on

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.

<div class="location">
    <p>latitude: <span id="lat"></span></p>
</div>

<script>
    var geostore = ContextHub.getStore("geolocation");
    geostore.eventing.on(ContextHub.Constants.EVENT_DATA_UPDATE,getlat,"getlat");

    function getlat(){
       latitude = geostore.getItem("latitude");
       $("#lat").html(latitude);
    }
</script>

once(name, handler, selector, triggerForPastEvents) 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.

Parameters parameters-once

Returns returns-once

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

If triggerForPastEvents is false, this function returns no value.

ContextHub.Utils.inheritance contexthub-utils-inheritance

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

Functions (ContextHub.Utils.inheritance) functions-contexthub-utils-inheritance

inherit(child, parent) inherit-child-parent

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

Parameters parameters-inherit

ContextHub.Utils.JSON contexthub-utils-json

Provides functions for serializing objects into JSON format and deserializing JSON strings into objects.

Functions (ContextHub.Utils.JSON) functions-contexthub-utils-json

parse(data) parse-data

Parses a string value as JSON and converts it into a javascript object.

Parameters parameters-parse

Returns returns-parse

A JavaScript object.

Example example-parse

The code:

ContextHub.Utils.JSON.parse("{'city':'Basel','country':'Switzerland','population':'173330'}");

Returns the following object:

Object {
   city: "Basel",
   country: "Switzerland",
   population: 173330
}

stringify(data) stringify-data

Serializes JavaScript values and objects into string values of JSON format.

Parameters parameters-stringify

Returns returns-stringify

The serialized string value. When data is a R egExp value, this function returns an empty object. When data is a function, returns undefined.

Example example-stringify

The following code:

ContextHub.Utils.JSON.stringify({
   city: "Basel",
   country: "Switzerland",
   population: 173330
});

Returns:

"{'city':'Basel','country':'Switzerland','population':'173330'}":

ContextHub.Utils.JSON.tree 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) functions-contexthub-utils-json-tree

addAllItems() 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 parameters-addallitems-1

Returns returns-addallitems-1

An object that contains the merged data.

cleanup() 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 parameters-cleanup

Returns returns-cleanup

A copy of tree that is cleaned.

getItem() getitem

Retrieves the value from an object for the key.

Parameters parameters-getitem-2

Returns returns-getitem-2

The value that corresponds 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.

Example example-getitem-2

Consider the following JavaScript object:

myObject {
  user: {
    location: {
      city: "Basel",
        details: {
          population: 173330,
          elevation: 260
        }
      }
    }
  }

The following example code returns the value 260:

ContextHub.Utils.JSON.tree.getItem(myObject, "/user/location/details/elevation");

The following example code retrieves the value for a key that has child keys:

ContextHub.Utils.JSON.tree.getItem(myObject, "/user");

The function returns the following object:

Object {
  location: {
    city: "Basel",
    details: {
      population: 173330,
      elevation: 260
    }
  }
}

getKeys() getkeys

Retrieves all keys from the data tree of an object. Optionally, you can retrieve only the keys of the children of a specific key. You can also optionally specify a sort order of the retrieved keys.

Parameters parameters-getkeys-2

Returns returns-getkeys-2

An array of keys.

Example example-getkeys-2

Consider the following object:

myObject {
  location: {
    weather: {
      temperature: "28C",
      humidity: "77%",
      precipitation: "10%",
      wind: "8km/h"
    },
    city: "Basel",
    country: "Switzerland",
    longitude: 7.5925727,
    latitude: 47.557421
  }
}

The ContextHub.Utils.JSON.tree.getKeys(myObject); script returns the following array:

["/location", "/location/city", "/location/country", "/location/latitude", "/location/longitude", "/location/weather", "/location/weather/humidity", "/location/weather/precipitation", "/location/weather/temperature", "/location/weather/wind"]

removeItem() removeitem

Creates a copy of a given object, removes the specified branch from the data tree, and returns the modified copy.

Parameters parameters-removeitem-2

Returns returns-removeitem-2

A copy of the original data object with the key removed.

Example example-removeitem-2

Consider the following object:

myObject {
  one: {
    foo: "bar",
    two: {
      three: {
        four: {
          five: 5,
          six: 6
        }
      }
    }
  }
}

The following example script removes the /one/two/three/four branch from the data tree:

myObject = ContextHub.Utils.JSON.tree.removeItem(myObject, "/one/two/three/four");

The function returns the following object:

myObject {
  one: {
    foo: "bar"
  }
}

sanitizeKey(key) sanitizekey-key

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

Use the resultant array to create a usable key.

Parameters parameters-sanitizekey

Returns returns-sanitizekey

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

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:

var key = " / this////is/a/path ";
ContextHub.Utils.JSON.tree.sanitizeKey(key)
"/" + ContextHub.Utils.JSON.tree.sanitizeKey(key).join("/");

setItem(tree, key, value) 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 parameters-setitem-2

Returns returns-setitem-2

A copy of the tree object that includes the key/ value pair.

Example example-setitem-2

Consider the following JavaScript code:

var myObject = {
     user: {
        location: {
           city: "Basel"
           }
        }
     };

var myKey = "/user/location/details";

var myValue = {
      population: 173330,
      elevation: 260
     };

myObject = ContextHub.Utils.JSON.tree.setItem(myObject, myKey, myValue);

ContextHub.Utils.storeCandidates contexthub-utils-storecandidates

Enables you to register store candidates and obtain registered store candidates.

Functions (ContextHub.Utils.storeCandidates) functions-contexthub-utils-storecandidates

getRegisteredCandidates(storeType) getregisteredcandidates-storetype

Returns the store types that are registered as store candidates. Either retrieve the registered candidates of a specific store type or of all store types.

Parameters parameters-getregisteredcandidates

Returns returns-getregisteredcandidates

An object of store types. The object properties are the store type names, and the property values are an array of registered store candidates.

getStoreFromCandidates(storeType) getstorefromcandidates-storetype

Returns a store type from the registered candidates. If more than one store type of the same name is registered, the function returns the store type with the highest priority.

Parameters parameters-getstorefromcandidates

Returns returns-getstorefromcandidates

An object that represents the registered store candidate. If the requested store Type is not registered, an error is thrown.

getSupportedStoreTypes() getsupportedstoretypes

Returns the names of the store types that are registered as store candidates. This function requires no parameters.

Returns returns-getsupportedstoretypes

An array of string values, where each string is the storetype with which a store candidate was registered. See the storeType parameter of the ContextHub.Utils.storeCandidates.registerStoreCandidate function.

registerStoreCandidate(store, storeType, priority, applies) 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 parameters-registerstorecandidate

Example example-registerstorecandidate

ContextHub.Utils.storeCandidates.registerStoreCandidate(myStoreCandidate,
                                'contexthub.mystorecandiate', 0);