Working with Content Selectors

 

A content selector is one of several mechanisms that WebLogic Personalization Server provides for retrieving documents from a content management system. A document is a graphic, a segment of HTML or plain text, or a file that must be viewed with a plug-in. (We recommend that you store most of your Web site's dynamic documents in a content management system because it offers an effective way to store and manage information.)

Using content selectors, a Business Analyst (BA) can specify conditions under which WebLogic Personalization Server retrieves one or more documents. For example, a BA can use a content selector to encapsulate the following conditions: between May 1 and May 10, if a Gold Customer views this page, find and retrieve any documents that describe sailing along the Maine coast.

A BA uses the BEA E-Business Control Center to define the conditions that activate a content selector and to define the query the content selector uses to find and retrieve documents. Then, a Commerce Business Engineer (CBE) creates content selector JSP tags and a set of other JSP tags that display the content the content selector retrieves in JSPs.

This topic includes the following sections:

• What Are Content Selectors?

• Using Content-Selector Tags and Associated JSP Tags

• How Content Selectors Select Documents

For a comparison of content retrieval methods available with WebLogic Personalization Server, refer to Methods for Retrieving and Displaying Documents.

 

---

What Are Content Selectors?

Content selectors specify conditions under which they query the content management system for documents. They consist of the following elements:

• A set of conditions that determine when the content selector queries the content management system. The conditions can use the profile of the customer who is currently viewing a JSP page, properties from the user or session objects, or an event that occurs on the page or has occurred previously on some other page, or the current date/time. For a complete list of conditions, refer to "Conditions That Activate Content-Selector Queries," under "Retrieving Documents with Content Selectors" in Using the E-Business Control Center.

  BAs create and modify the set of conditions in the E-Business Control Center.

• A query that searches the content management system for one or more documents.

  BAs create and modify the query in the E-Business Control Center.

• A JSP tag that triggers the content selector to evaluate its conditions. The content selector JSP tag includes attributes that CBEs can use to tune the performance of the content selection process. CBEs create the JSP tags.

• A data object that WebLogic Personalization Server creates to contain the results of the query. Within the data object, WebLogic Personalization Server creates a list of individual data items (an array); the contents of each document in the data object is a separate item in the array. You can access the array only from the current JSP page, and only for the customer request that created it.

  To extend the availability of the data in the array, CBEs can add attributes to the content selector JSP tag that cause WebLogic Personalization Server to store the array in a cache. Then, CBEs specify whether the scope of the cache applies to the application, session, page, or request.

To display the documents that are in the array (or the cache), a CBE must use the <es:forEachInArray> tag. Depending on the scope of the cache, a <es:forEachInArray> can access a content-selector cache that WebLogic Personalization Server created for another page and for another user.

 

---

Using Content-Selector Tags and Associated JSP Tags

To use the content selector features on a given JSP, a CBE must add calls to the content selector JSP tag and a set of associated tags.

This section contains the following subsections:

• Attributes of the <pz:contentSelector> Tag

• Associated Tags That Support Content Selectors

• Common Uses of Content-Selector Tags and Associated Tags

Attributes of the <pz:contentSelector> Tag

While BAs use the E-Business Control Center to configure the dynamic properties of a content selector, a CBE uses attributes of the content selector tag to do the following:

• Identify the Content Selector Definition

• Identify the JNDI Home for the Content Management System

• Define the Array That Contains Query Results

• Create and Configure the Cache to Improve Performance

For a complete list and description of all content-selector attributes, refer to <pz:contentSelector> in the Personalization Server JSP Tag Library Reference chapter of this guide.

Identify the Content Selector Definition

The content selector definition that a BA creates in the E-Business Control Center determines the conditions that activate a content selector and the query that the active content selector runs.

To refer to this definition, you use the rule attribute:

<pz:contentSelector rule= { definition-name | scriptlet } >

You can use a scriptlet to determine the value of the rule attribute based on additional criteria. For example, you use a content selector in a heading JSP (heading.inc), which is included in other JSPs. A BA creates different content selectors for each page that includes heading.inc.

The CBE uses a scriptlet in heading.inc to provide a value based on the page that currently displays the included JSP file. For example,

<% 

   String banner = (String)pageContext.getAttribute("bannerPh");
   banner = (banner == null) ? "cs_top_generic" : banner;

%>

<!-- ------------------------------------------------------------- -->

<table width="100%" border="0" cellspacing="0" cellpadding="0" height="108">

  <tr><td rowspan="2" width="147" height="108">
  <pz:contentSelector rule="<%= banner %>" ... />

</td>

Identify the JNDI Home for the Content Management System

The content selector tag must use the contentHome attribute to specify the JNDI home of the content management system. If you use the reference content management system or a third-party integration, you can use a scriptlet to refer to the default content home. Because the scriptlet uses the ContentHelper class, you must first use the following tag to import the class into the JSP:

<%@ page import="com.beasys.commerce.content.ContentHelper"%>

Then, when you use the content selector tag, specify the contentHome as follows:

<pz:contentSelector
contentHome="<%=ContentHelper.DEF_DOCUMENT_MANAGER_HOME %>"
... />

If you create your own content management system, you must specify the JNDI home for your system instead of using the ContentHelper scriptlet. In addition, if your content management system provides a JNDI home, you can specify that one instead of using the ContentHelper scriptlet.

Define the Array That Contains Query Results

You can use the following attributes to configure the array that contains the results of the content-selector query:

• id, which specifies a name for the array. This attribute is required.

  For example, <pz:contentSelector id="docs" .../> places documents in an array named docs.

• max, which limits the number of documents the content selector places in its array.

  For example, <pz:contentSelector max="10" .../> causes the content selector to stop retrieving documents when the array contains 10 documents.

  This attribute is optional and defaults to -1, which means no maximum.

• sortBy, which uses one or more document attribute to sort the documents in the array. The syntax for sortBy follows the SQL order by clause syntax.

  This attribute is optional. If you do not specify this attribute, the content selector returns the query results in the order that the content management system returns them.

  For example, <pz:contentSelector sortBy="creationDate" .../> places the documents that were created first at the beginning of the array.

  The tag
  <pz:contentSelector sortBy="creationDate ASC, title DESC" .../>
  places older documents at the beginning of the array. If any documents were created on the same day, it sorts those documents counter-alphabetically by title.

Create and Configure the Cache to Improve Performance

To extend accessibility to the array, and to improve performance, you can optionally use content-selector attributes to create and configure a cache that contains the array contents. Without the cache, you can access the content-selector array only from the current JSP page, and only for the customer request that created it. In addition, each time a customer requests a JSP that contains the content selector tag, the content selector must run the query, potentially slowing the overall performance of WebLogic Personalization Server. To cache the contents of the array, define the following attributes:

• useCache, which determines whether the content selector places the array in a cache. To activate the cache, set this attribute to true. For example, <pz:contentSelector cache=true ...>.

  To deactivate the cache, set the attribute to false or do not include it. For example, the following statements are equivalent:
  <pz:contentSelector cache=false .../> or
  <pz:contentSelector .../>

• cacheID, which assigns a name to the cache. If you do not specify this attribute, the cache uses the name of the array (which you must specify with the id attribute). If you want to access the cache from a JSP or user session other than the one that created the array, you must specify a cacheID.

• cacheTimeout, which specifies the number of milliseconds that WebLogic Personalization Server maintains the cache. The content selector does not re-run the query until the number of seconds expires.

  For example, you create the following tag:
  <pz:contentSelector cache=true cacheTimeout="300000" .../>

  A customer requests the page that contains this content selector tag. The user leaves the page but, 2 minutes (120000 milliseconds) later, requests it again. The content selector evaluates its conditions, but because only 120000 milliseconds have expired since the content selector created the cache, it does not re-run the query. Instead, it displays the documents in the cache.

• cacheScope, which determines from where the cache can be accessed. You can provide the following values for this attribute:

  • application. Any JSP page in the Web application that any customer requests can access the cache.

  • session (the default). Any JSP in the Web application that the current customer requests can access the cache.

  • page. Only the current JSP that any customer requests can access the cache.

  • request. Only the current user request can access the cache. If a customer re-requests the page, the content selector re-runs the query and recreates the cache.

Associated Tags That Support Content Selectors

The following JSP tags support content-selector functions:

• <um:getProfile>, which retrieves the profile of the customer who is currently viewing the page. A content selector uses the customer profile to evaluate any conditions that involve customer properties.

  For example, if you create a content selector that runs a query for all customers in the Gold Customer customer segment, the content selector must access the customer profile to determine if it matches the customer segment.

  Even if a content selector does not currently use the customer profile for its conditions, we recommend that you include the <um:getProfile> tag; its affect on performance is minimal and with the tag, a BA can add customer-profile conditions to the content selector without requiring a CBE to modify JSPs.

  The tag must be located closer to the beginning of the JSP than the content selector tag.

• <es:forEachInArray>, which iterates through the array that contains the results of a content-selector query. With this tag, you can use the following to work with the documents in the array:

  • The System.out.println method to print each item in the array.

  • The <cm:getProperty> tag to retrieve one or more attribute of the documents in the array. You can use the attributes to construct the HTML that a browser requires to display the documents. For example, you use the <cm:getProperty> tag to determine the value of a MIME-type attribute. If the MIME-type of a document in the array is an image, you print the HTML <img> tag with the appropriate attributes.

    You can also use attributes of the <pz:contentSelector> tag, such as sortBy, to work with the attributes of documents in the array. For more information, refer to Attributes of the <pz:contentSelector> Tag.

  • The <cm:printProperty> to print one or more attribute of the documents in the array. For example, you can use this tag to print a list of document titles that the content selector retrieves.

Common Uses of Content-Selector Tags and Associated Tags

The combination of content selector definitions, tag attributes, and associated JSP tags creates a powerful set of tools for matching documents to customers in specific contexts. The following tasks are the most common uses of content selectors and associated tags:

• To Retrieve and Display Text-Type Documents

• To Retrieve and Display Image-Type Documents

• To Retrieve and Display a List of Documents

• To Access a Content-Selector Cache on a Different JSP

To Retrieve and Display Text-Type Documents

Note: This section assumes that the content selector query that the BA created in E-Business Control Center includes a filter to retrieve only text documents.

1. Open a JSP in a text editor.

2. Near the beginning of the JSP, add the following lines to import classes and tag libraries if they are not already in the JSP:

   <%@ page import="com.beasys.commerce.content.ContentHelper"%> <%@ taglib uri="es.tld" prefix="es" %>
   <%@ taglib uri="pz.tld" prefix="pz" %>
   <%@ taglib uri="um.tld" prefix="um" %>

3. Add the following tag to get the customer profile, if the tag is not already in the JSP:

   <um:getProfile>

   If the JSP already uses this tag for some other purpose, it probably includes other attributes. Make sure that the tag is closer to the beginning of the JSP than the <pz:contentSelector> tag, which you create in the next step.

4. Add the following tags, where SpringSailing is the name of the content selector that a BA created in the E-Business Control Center:

   <pz:contentSelector rule="SpringSailing"
   contentHome="<%=ContentHelper.DEF_DOCUMENT_MANAGER_HOME %>"
   id="textDocs"/>
   <es:forEachInArray array="<%=textDocs%>" id="aTextDoc" type="com.beasys.commerce.axiom.content.Content">

   <% "<P>" + aTextDoc + "</P>" %>

   </es:forEachInArray>

   Note: The above tags assume that the content selector query that the BA created in the E-Business Control Center includes a filter to retrieve only text documents. To verify the content type before you display it, you can surround the <% "<P>" + aTextDoc + "</P>" %> scriptlet with another scriptlet. For example:

   <% if (aTextDoc .getMimeType().contains("text"))
   {
   <% "<P>" + aTextDoc + "</P>" %>
   }
   %>

5. Save the JSP. If you deploy the Web application as a WAR file, re-jar the Web application and deploy it.

   WebLogic Personalization Server deploys the modifications. If you specified a page-check rate for your Web application, WebLogic Personalization Server waits for the page-check interval to expire before deploying any changes. For more information on setting the page-check interval, refer to the Performance Tuning Guide.

To Retrieve and Display Image-Type Documents

1. Determine the name of the attribute that your content management system uses to uniquely identify documents. This procedure assumes that your content management system uses an attributed named docID.

2. Open a JSP in a text editor.

3. Near the beginning of the JSP, add the following lines to import classes and tag libraries if they are not already in the JSP:

   <%@ page import="com.beasys.commerce.content.ContentHelper"%> <%@ taglib uri="es.tld" prefix="es" %>
   <%@ taglib uri="pz.tld" prefix="pz" %>
   <%@ taglib uri="um.tld" prefix="um" %>
   <%@ taglib uri="cm.tld" prefix="cm" %>

4. Add the following tag to get the customer profile, if the tag is not already in the JSP:

   <um:getProfile>

   If the JSP already uses this tag for some other purpose, it probably includes other attributes. Make sure that the tag is closer to the beginning of the JSP than the <pz:contentSelector> tag, which you create in the next step.

5. Add the following tags, where SpringSailing is the name of the content selector that a BA created in the E-Business Control Center:

   <pz:contentSelector rule="SpringSailing"
   contentHome="<%=ContentHelper.DEF_DOCUMENT_MANAGER_HOME %>"
   id="ImageDocs"/>

   <es:forEachInArray array="<%=ImageDocs%>" id="anImageDoc" type="com.beasys.commerce.axiom.content.Content">

   <img src="<cm:printProperty id="anImageDoc" rule="docID"
   encode="URL">" >

   </es:forEachInArray>

   Note: The above tags assume that the content selector query that the BA created in E-Business Control Center includes a filter to retrieve only image documents. To verify the content type before you display it, you can surround the <img> tag with a scriptlet. For example:

   <% if (anImageDoc .getMimeType().contains("image"))
   {
   <img src="<cm:printProperty id="anImageDoc" rule="docID"
   encode="URL">" >
   }
   %>

6. Save the JSP. If you deploy the Web application as a WAR file, re-jar the Web application and deploy it.

   WebLogic Personalization Server deploys the modifications. If you specified a page-check rate for your Web application, WebLogic Personalization Server waits for the page-check interval to expire before deploying any changes. For more information on setting the page-check interval, refer to the Performance Tuning Guide.

To Retrieve and Display a List of Documents

1. Open a JSP in a text editor.

2. Near the beginning of the JSP, add the following lines to import classes and tag libraries if they are not already in the JSP:

   <%@ page import="com.beasys.commerce.content.ContentHelper"%> <%@ taglib uri="es.tld" prefix="es" %>
   <%@ taglib uri="pz.tld" prefix="pz" %>
   <%@ taglib uri="um.tld" prefix="um" %>

3. Add the following tag to get the customer profile, if the tag is not already in the JSP:

   <um:getProfile>

   If the JSP already uses this tag for some other purpose, it probably includes other attributes. Make sure that the tag is closer to the beginning of the JSP than the <pz:contentSelector> tag, which you create in the next step.

4. Add the following tags, where SpringSailing is the name of the content selector that a BA created in the E-Business Control Center:

   <pz:contentSelector rule="SpringSailing" <pz:contentSelector rule="SpringSailing"
   contentHome="<%=ContentHelper.DEF_DOCUMENT_MANAGER_HOME %>"
   id="docs"/>

   <ul>
   <es:forEachInArray array="<%=docs%>" id="aDoc"
   type="com.beasys.commerce.axiom.content.Content">

   <li>The document title is: <cm:printProperty id="aDoc"
   rule="Title" encode="html" />

   </es:forEachInArray>

   </ul>

5. Save the JSP. If you deploy the Web application as a WAR file, re-jar the Web application and deploy it.

   WebLogic Personalization Server deploys the modifications. If you specified a page-check rate for your Web application, WebLogic Personalization Server waits for the page-check interval to expire before deploying any changes. For more information on setting the page-check interval, refer to the Performance Tuning Guide.

To Access a Content-Selector Cache on a Different JSP

1. In a text editor, open the JSP page that contains the content selector tag. For example, you want to cache the results of the following tag:
   <pz:contentSelector rule="SpringSailing" id="docs".../>

2. Add attributes to the content selector tag as follows:

   <pz:contentSelector rule="SpringSailing"
   contentHome="<%=ContentHelper.DEF_DOCUMENT_MANAGER_HOME %>"
   id="docs"
   useCache=true cacheID="SpringSailingDocs" cacheTimeout="120000"
   cacheScope="application" />

   These attributes create a cache that WebLogic Personalization Server maintains for 2 minutes (120000 milliseconds) and that can be accessed using the name SpringSailingDocs by any user from any page in the Web application. For more information about possible values for cacheScope, refer to Create and Configure the Cache to Improve Performance.

3. Save and deploy the JSP.

4. In a text editor, open the JSP from which you want to access the cache.

5. Use a content-selector tag that is identical to the tag you created in step 2. For example, on the current JSP, add the following tag:
   <pz:contentSelector rule="SpringSailing"
   contentHome="<%=ContentHelper.DEF_DOCUMENT_MANAGER_HOME %>"
   id="docs"
   useCache=true cacheID="SpringSailingDocs" cacheTimeout="120000"
   cacheScope="application" />

6. Add tags to retrieve the data from the cache. For example, the following lines print a list of documents that are in the cache:

   <%@ taglib uri="es.tld" prefix="es" %>

   <ul>
   <es:forEachInArray array="<%=SpringSailingDocs%>" id="aDoc"
   type="com.beasys.commerce.axiom.content.Content">

   <li>The document title is: <cm:printProperty id="aDoc"
   rule="Title" encode="html" />

   </es:forEachInArray>

   </ul>

7. Save and deploy the JSP.

 

---

How Content Selectors Select Documents

When a user requests a JSP that contains a content selector tag, the following process occurs:

1. The content selector tag contacts the Advisor.

Note: For information about the Advisor, see Creating Personalized Applications with the Advisor.
For information about the Rules Engine, see Introducing the Rules Manager.

1. The Advisor forwards the content-selector request to the Rules Manager via the Rules Advislet.

2. The Rules Manager finds the corresponding content-selector definition and invokes the Rules Engine to evaluate the content selector's conditions.

3. Depending on the conditions that are defined for the content selector, the Rules Engine refers to any of the following:

   • The profile of the user who requested the JSP to determine if the user matches a customer segment or some other attribute that conditions in the content selector specify.

   • The Events Service to determine if any events that conditions in the content selector specify have occurred.

   • The system clock to determine if the current time or date matches any time or date that conditions in the content selector specify.

4. If any of the conditions are met, the Rules Engine returns the content selector's query to the Advisor via the Rules Manager.

5. The Advisor forwards the query to the content management system via the Content Query Advislet.

6. The Advisor stores any query results in an array that only the current JSP can access. You can specify that the Advisor stores the results in a cache and that the cache is accessible beyond the current JSP. For more information, see Create and Configure the Cache to Improve Performance.

Note that you must use other tags to display the documents that are in the array.

Figure 1-4 How Content Selectors Select Documents

 

For more information about using this tag, refer to Using Content-Selector Tags and Associated JSP Tags.