Interaction Management Guide

Content Selectors

Content selectors are a powerful tool for personalization, letting you target specific groups of people with one or more specific content items from the BEA's Virtual Content Repository.

For example, if a user logs in who is identified in her user profile as a "book nerd," a content selector can display a list of recommended books.

A content selector is made up of two parts: a content selector file you create in WebLogic Workshop and a companion JSP tag that performs the processing.

In Figure 3-1, the content selector file is called "classic", and the JSP tag references the content selector file.

Figure 3-1 The two parts of a content selector: a content selector file and a JSP tag

The two parts of a content selector: a content selector file and a JSP tag

This chapter includes the following sections:

How Content Selectors Work

Users do not have to be authenticated (log in) to be targeted by content selectors. For example, the presence of specific HTTP request or session properties, or specific date/time conditions can trigger content to be displayed. You can, for example, display targeted holiday content to users who visit your portal in the month of December and who are viewing your portal with a specific type of Web browser.

However, authenticated users (as well as anonymous tracked users) have profile information associated with them that you can use to target them more accurately with personalized content. The "book nerd" example in the chapter introduction is an example of this.

The following sections describe the structure of a content selector in more detail: the content selector file and the JSP tag.

Content Selector File

A content selector file contains two parts:

The personalization rules—the conditions that define when the content selector runs its query and displays the content. The following conditions can be used to trigger a content selector:

The visitor is a member of a predefined user segment.
The visitor has specific characteristics (user profile properties).
Specific HTTP session or request properties exist.
Date/time conditions.

A content query that retrieves a specific set of content properties.

Figure 3-2 shows a content selector file called classic.sel. The condition that triggers the content selector is a user whose user profile has a "Graphic Preference" property with a value of "classic". The content that is retrieved is any content with a binary file name that contains "IRACampaign".

Figure 3-2 Content selector file in WebLogic Workshop

Content selector file in WebLogic Workshop

<pz:contentSelector> JSP Tag

After you have created a content selector file, you must use the <pz:contentSelector> JSP tag to display the content. Following is an JSP tag for the "classic" content selector shown in Figure 3-2.

<pz:contentSelector rule="classic" id="nodes"/>

The JSP tag has two required attributes:

rule - Contains the name of the content selector file (without the file extension). This tells the JSP tag which personalization rules and query to use.
id - When a content selector runs its query and retrieves content from the Virtual Content Repository, the content is retrieved as an array of content properties. The id attribute, which is a String you enter, serves as a container that holds the array. At this point, you must use other JSP tags to handle the array and display the content. For details on what you can do with the array of properties to display the content, see Using Content Selectors in this chapter.

There are many other useful attributes you can set on the <pz:contentSelector> tag. See "<pz:contentSelector> Tag" in the WebLogic Workshop help system at http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/portal/taglib/www.bea.com/servers/portal/tags/personalization/contentSelector.html

Types of Content that Content Selectors Can Display

Content selectors retrieve content properties, most of which are the text or numeric values. For example, say you want your content selectors to retrieve information about books. Book content can be assigned many properties, such as title, author, publication date, ISBN, and a URL to the publisher's Web site. You may want your content selector to display a bulleted list of titles and link each title to the publisher's Web site. All of that is accomplished through using only the text values of the content properties.

But say book content also has a binary property that stores an image of the book's cover. The content selector can also display that binary property—show the actual image—using the ShowProperty servlet, as described in Using Content Selectors. The the type of binary content that content selectors can display is dependent upon the MIME types you have configured. By default, WebLogic Portal provides MIME support for displaying image, Shockwave, and XHTML files. To display content for other MIME types, see "Supporting Additional MIME Types" in the WebLogic Workshop help system at http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/portal/buildportals/mimetypes.html.

Setting up Content for Use in Content Selectors

For content selectors to display binary content such as images, the binary content property must be set to "Primary Property" in the Virtual Content Repository. See "Displaying Binary Content" in the Setting up Content chapter in this guide.

Creating Content Selectors

Creating a placeholder involves creating a content selector file in WebLogic Workshop and using companion <pz:contentSelector> JSP tags in any relevant JSPs. Each <pz:contentSelector> JSP tag must use its "rule" attribute to reference a content selector you have created in WebLogic Workshop, and it must use its "id" attribute to store the array of the content query results.

For steps on creating content selectors, see the following topics in the WebLogic Workshop Help system:

"Creating Content Selectors" at http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/portal/buildportals/createSelectors.html.
"<pz:contentSelector> Tag" at http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/portal/taglib/www.bea.com/servers/portal/tags/personalization/contentSelector.html.

Tutorial

The WebLogic Workshop help system includes a tutorial called "Showing Personalized Content in a Portlet" at http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/portal/tutorials/tutP13nPortletIntro.html. This tutorial involves creating content selectors and surfacing the content in a portlet.

Building Content Queries

WebLogic Portal provides advanced content query features for building powerful content queries. For more information, see "Building Content Queries with Expressions" in the WebLogic Workshop help system at http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/portal/buildportals/contentExpression.html.

Adding Content Selectors to JSPs

After you create a content selector file in WebLogic Workshop, you can add the content selector to a JSP in a number of ways in WebLogic Workshop:

Drag a placeholder from the Application window onto a page of an open portal file. When you do this, three things happen:

The Portlet Wizard appears, letting you quickly create a portlet that will display the placeholder.
The resulting portlet is automatically added to the portal page.
A JSP file is automatically created for the content selector.

The JSP file contains the content selector JSP tag with the "rule" and "id" attributes automatically populated, and the include statement for the tag library is automatically added.
Other JSP and HTML tags are also added automatically: <pz:contentSelector rule="modern" id="nodes"/> <utility:notNull item="<%=nodes%>"> <ul> <utility:forEachInArray array="<%=nodes%>" id="node" type="com.bea.content.Node"> <li><cm:getProperty id="node" name="cm_nodeName" conversionType="html"/></li> </utility:forEachInArray> </ul> </utility:notNull>
Table 3-1 describes the additional tags. Table 3-1 Tags to use in conjunction with content selectors <utility:notNull> Checks to see if the array actually contains content. <ul> Provides a container for listing content items in a bulleted list. <utility:forEachInArray> Iterates through the array and isolates each content item until all items in the array have been processed. Each item is given its own <li> bullet. <cm:getProperty> Takes each content item from <utility:forEachInArray> and designates which content property is going to be displayed.

Open the JSP to which you want to add the content selector, and drag the content selector file from the Application window into the JSP in either Design View or Source View. The JSP tag is added automatically, the "rule" attribute is automatically populated with the name of the placeholder, the "id" attribute is included (without a value), and the tag library include statement is added automatically. See Figure 3-1.
Drag the <pz:contentSelector> JSP tag from the Palette window (the Portal Personalization category) into an open JSP and populate the tag's attributes manually. The tag library include statement is added automatically.

Using Content Selectors

This section provides guidance on using content selectors.

Create a content selector for each audience you want to target. If you have five audiences you want to target with content, create five content selectors, then add five <pz:contentSelector> tags to your JSP, each of which references its own content selector file.
When a content selector is triggered and runs its query, the results (content properties) are returned to the <pz:contentSelector> JSP tag and stored in the tag's "id" attribute. At this point, you need other tags or code to process and display the content. The tags described Table 3-1 are among the most useful tags for displaying retrieved content.
To display binary content retrieved by content selectors, use the ShowProperty servlet. The following code example shows how:

<pz:contentSelector rule="classic" id="nodes"/>

<utility:notNull item="<%=nodes%>">

<ul>

<utility:forEachInArray array="<%=nodes%>" id="node" type="com.bea.content.Node">

<img src="<%=request.getContextPath() + "/ShowProperty" + node.getPath()%>">

</utility:forEachInArray>

</ul>

</utility:notNull>

The <img> HTML tag's source path is constructed to use the path to the content item in the Virtual Content Repository. The path includes the ShowProperty servlet to render the binary file. In the node.getPath() method, node is a specific content item stored by the <utility:forEachInArray> tag's "id" attribute. If the <utility:forEachInArray> "id" attribute value was "foo", the method would look like this: foo.getPath().

Using <pz:div> Instead of a Content Selector

With the <pz:div> JSP tag, you can provide in-line HTML personalization. You can populate a JSP with sets of inline content and wrap it with the tag. The tag uses a "rule" attribute that takes the name of an existing user segment. Only members of that user segment can see the inline content. For example, say you have created a user segment called booknerdUserSegment.seg in WebLogic Workshop that makes anyone a member who has a "bookNerd" user profile property set to "true". You could do the following:

<pz:div rule="booknerdUserSegment">

	<p>Only users who are book nerds will see this text!</p>

</pz:div>

User segment rules (conditions) are the same as those available to content selectors, so the <pz:div> tag provides a similar level of personalization as content selectors. The difference is that content selectors retrieve their content from the Virtual Content Repository, and <pz:div> encloses its content inline in the JSP.

`<utility:notNull>`	Checks to see if the array actually contains content.
`<ul>`	Provides a container for listing content items in a bulleted list.
`<utility:forEachInArray>`	Iterates through the array and isolates each content item until all items in the array have been processed. Each item is given its own `<li>` bullet.
`<cm:getProperty>`	Takes each content item from `<utility:forEachInArray>` and designates which content property is going to be displayed.