Client Context in Detail

The Client Context represents a dynamically assembled collection of user data. You can use the data to determine the content to show on a web page in a given situation (content targeting). The data is also available for web site analytics, and to any javascript on the page.

Client Context consists mainly of the following aspects:

• The session store, that contains the user data.
• The UI that displays the user data and provides tools for simulating the user experience.
• A javascript API for interacting with session stores.

To create a standalone session store and add it to Client Context, or create a session store that is tied to a Context Store component. AEM installs several Context Store components that you can use right away. You can use these components as a basis for your components.

For information about opening Client Context, configuring the information that it displays, and simulating the user experience, see Client Context.

The Client Context includes various session stores that contain user data. Store data comes from the following sources:

• The client web browser.
  
• The server (see JSONP Store for storing information from 3rd-party sources)
  

The Client Context framework provides a javascript API that you can use to interact with session stores to read and write user data, and listen and react to store events. You can also create session stores for user data that you use for content targeting or other purposes.

Session store data remains on the client. The Client Context does not write data back to the server. To send data to the server, use a form or develop custom javascript.

Each session store is a collection of property-value pairs. The session store represents a collection of data (of any kind), the conceptual meaning of which can be decided by the designer and/or developer. The following example javascript code defines an object that represents the profile data that session store might contain:

A session store can be persisted across browser sessions, or can last only for the browser session in which it is created.

A context store component is a CQ component that can be added to Client Context. Typically, context store components display data from a session store with which they are associated. However, the information that context store components display is not limited to session store data.

Context store components can include the following items:

• JSP scripts that define the appearance in Client Context.
• Properties for listing the component in Sidekick.
• Edit dialogs for configuring component instances.
• Javascript that initializes the session store.

For a description of the installed Context Store Components that you can add to Context Store, see Available Client Context Components.

Profile information is also used for delivering targeted content.

Include the Client Context component to the body section of your web pages to enable Client Context. The path of the Client Context component node is /libs/cq/personalization/components/clientcontext. To include the component, add the following code to the JSP file of your page component, located just below the body element of your page:

The clientcontext component causes the page to load the client libraries that implement Client Context.

• The Client Context javascript API.
• The Client Context framework that supports session stores, event management, etc.
• Segments that are defined.
• The init.js scripts that are generated for each context store component that has been added to Client Context.
• (Author instance only) The Client Context UI. 

The Client Context UI is available only on the author instance.

To extend Client Context, create a session store and optionally display the store data:

• Create a session store for the user data that you need for content targeting and web analytics.
• Create a context store component to enable administrators to configure the associated session store, and to display store data in Client Context for testing purposes. 

Create a session store for the data that you need to add to and retrieve from Client Context. Generally, you use the following procedure to create a session store:

1. Create a client library folder that has a categories property value of personalization.stores.kernel. Client Context automatically loads the client libraries of this category.
2. Configure the client library folder so that it has a dependency on the personalization.core.kernel client library folder. The personalization.core.kernel client library provides the Client Context javascript API.
3. Add the javascript that creates and initializes the session store.

Including the javascript in the personalization.stores.kernel client library causes the store to be created when the Client Context framework is loaded.

Session stores are either created and available during a browser session, or are persisted in browser storage or cookies. The Client Context javascript API defines several classes that represent both types of data stores:

• CQ_Analytics.SessionStore: These objects reside only in the page DOM. The data is created and persisted during the lifetime of the page.
• CQ_Analytics.PerstistedSessionStore: These objects reside in the page DOM and are persisted either in browser storage or cookies. The data is available across pages and across user sessions.

The API also provides extensions of these classes that are specialized for storing JSON data or JSONP data: 

• Session-only objects: CQ_Analytics.JSONStore and CQ_Analytics.JSONPStore.
• Persisted objects: CQ_Analytics.PersistedJSONStore and CQ_Analytics.PersistedJSONPStore.

The javascript of your client library folder creates and initializes the session store. The session store must then be registered using Context Store Manager.  The following example creates and registers a CQ_Analytics.SessionStore object.

For storing JSON data, the following example creates and registers a CQ_Analytics.JSONStore object.

Create a context store component to render session store data in Client Context. Once created, you can drag your context store component onto Client Context to render data from a session store. Context store components consist of the following items:

• JSP script for rendering the data.
• An edit dialog.
• A JSP script for initializing the session store.
• (Optional) A client library folder that creates the session store. There is no need to include the client library folder if the component uses an existing session store.

AEM provides the genericstore and the genericstoreproperties context store components that you can extend. The structure of your store data determines the component that you extend:

• Property-value pairs: Extend the GenericStoreProperties component. This component automatically renders stores of property-value pairs. Several interaction points are supplied:
  • prolog.jsp and epilog.jsp: component interaction that allows you to add server side logic before or after the component rendering.
• Complex data: Extend the GenericStore component. Your session store will then need a "renderer" method that will be called every time the component needs to be rendered. The renderer function is called with two parameters:
  • @param {String} store
    The store to render
  • @param {String} divId
    Id of the div into which the store has to be rendered.

When editing Client Context, context store components appear in Sidekick. As with all components, the componentGroup and jcr:title properties of the client context component determine the group and name of the component.

All components that have a componentGroup property value of Client Context appear in Sidekick by default. If you use a different value for the componentGroup property, you must manually add the component to Sidekick using Design mode. 

When you add a context store component to Client Context, a node that represents the component instance is created below /etc/clientcontext/default/content/jcr:content/stores. This node contains the property values that are configured using the edit dialog of the component.

When Client Context is initialized, these nodes are processed.

Add an init.js.jsp file to your component to generate javascript code that initializes the session store that your context store component uses. For example, use the intialization script to retrieve configuration properties for the component and use them to populate the session store.

The javascript that is generated is added to the page when Client Context is initialized on page load on both the author and publish instances. This JSP is executed before the context store component instance is loaded and rendered. 

The code must set  the mime type of the file to text/javascript, or it is not executed.

The following procedure creates the init.js.jsp script file and adds the code that sets the correct mime type. The code that performs the store initialization would follow.

Display session store data in Client Context using a consistent format.

The personalization taglib provides the personalization:storePropertyTag tag that displays the value of a property from a session store. To use the tag, include the following line of code in your JSP file:

The tag has the following format:

The propertyName attribute is the name of the store property to display. The store attribute is the name of the registered store. The following example tag displays the value of the authorizableId property of the profile store:

The personalization.ui client library folder (/etc/clientlibs/foundation/personalization/ui/themes/default) provides the CSS styles that Client Context uses to format the HTML code. The following code illustrates the suggested structure to use for displaying store data:

The /libs/cq/personalization/components/contextstores/profiledata context store component uses this structure to display data from the profile session store. The cq-cc-thumbnail class places the thumbnail image. The cq-cc-store-property-levelx classes format the alphanumeric data:

• level0, level1, and level2 are distributed vertically, and use a white font.
• level3, and any additional levels, are distributed horizontally, and use a white font with a darker background. 

To render store data using a genericstore component, you need to:

• Add the personalization:storeRendererTag tag to the component JSP script to identify the name of the session store.
• Implement a renderer method on the session store class.

The personalization taglib provides the personalization:storePropertyTag tag that displays the value of a property from a session store. To use the tag, include the following line of code in your JSP file:

The tag has the following format:

Your session store will then need a "renderer" method that will be called every time the component needs to be rendered. The renderer function is called with two parameters:

• @param {String} store
  The store to render
• @param {String} divId
  Id of the div into which the store has to be rendered.

Use javascript to interact with session stores.

Obtain a session store object to read or write data to the store. CQ_Analytics.ClientContextMgr provides access to stores based on the store name. Once obtained, use the methods of the CQ_Analytics.SessionStore or CQ_Analytics.PersistedSessionStore to interact with store data.

The following example obtains the profile store and then retrieves the formattedName property from the store.

Session stores fire events, so it is possible to add listeners and trigger events based on these events.

The session stores are built on the Observable pattern. They extend  CQ_Analytics.Observable that provides the addListener method.

The following example adds a listener to the update event of the profile session store.

Session stores are not available until they are loaded and initialized with data. The following factors can affect the timing of session store availability:

• Page loading
• JavaScript loading
• JavaScript execution time
• Response times for XHR requests
• Dynamic changes to the session store

Use the CQ_Analytics.ClientContextUtils object's onStoreRegistered and onStoreInitialized methods to access session stores only when they are available. These methods enable you to register event listeners that react to session registration and initialization events.

The following example uses the onStoreRegistered event of the profile session store. When the store is registered, a listener is added to the update event of the session store. When the store is updated, the content of the <div class="welcome"> element on the page is updated with the name from the profile store.

To prevent a property of a PersistedSessionStore from being persisted (i.e. exclude it from the sessionpersistence cookie), add the property to the non-persisted property list of the persisted session store.

See CQ_Analytics.PersistedSessionStore.setNonPersisted(propertyName)

The current page must have a corresponding mobile page; this is determined only if page has a LiveCopy configured with a mobile rollout configuration (rolloutconfig.path.toLowerCase contains mobile).

When switching from the desktop page to its mobile equivalent:

• The DOM of the mobile page is loaded.
• The main div (required) that contains the content, is extracted and injected into the current desktop page.
  
• The CSS and body classes that need to be loaded need to be manually configured.

For example:

In this example, you create a context store component that retrieves data from an external service and stores it in the session store:

• Extends the genericstoreproperties component.
• Initializes a store using a CQ_Analytics.JSONPStore javascript object.
• Calls a JSONP service to retrieve data and add it to the store.
• Renders the data in Client Context.

Create a CQ application and add the geoloc component.

The context store component requires an edit dialog. The geoloc edit dialog will contain a static message that indicates that there are no properties to configure.

Add an init.js.jsp file to the geoloc component and use it to create the session store, retrieve the location data, and add it to the store.

The init.js.jsp file is executed when the Client Context is loaded by the page. By this time, the Client Context javascript API is loaded and available to your script.

Add the code to the JSP file of the geoloc component to render the store data in Client Context.

Add the Location Store component to Client Context so that it is initialized when the page loads.

Open the Geometrixx Outdoors home page in edit mode and then open Client Context to see the data from the Location Store component.

To create a second client context you need to duplicate the branch:

    /etc/clientcontext/default

• The subfolder:
      /content
  will contain the content of the customized client context.
• The folder:
       /contextstores
  allows you to define different configurations for the context stores.

To use your customized client context, edit the property
    path
in the design style of the client context component, as included in the page template. For example, as the standard location of:
    /libs/cq/personalization/components/clientcontext/design_dialog/items/path