Setting Up Personalization and Interaction Management

e-docs > WebLogic Platform > WebLogic Portal > Development Guide > Setting Up Personalization and Interaction Management

Development Guide

Setting Up Personalization and Interaction Management

WebLogic Portal comes with robust authentication and personalization features that allow administrators to determine what content a visitor can interact with and how that information will appear to the specific visitor. Visitors themselves can leverage WebLogic Portals personalization features to select their own content and create their own look and feel. A major component of the portal development process is to create the resources by using such tools as the Advisor, the Rules Framework, and content selectors to make such authorization and personalization possible.

This section includes information on the following subjects:

Using the Advisor to Personalize a Portal Application

The WebLogic Portal Advisor is an easy-to-use and flexible access point for personalization services-including personalized content, user segmentation, and the underlying rules engine. The Advisor delivers content to a personalized application based on a set of rules and user profile information. It can retrieve any type of content from a Document Management system and display it in a JSP.

The Advisor ties together all the services and components in the system to deliver personalized content. The Advisor component includes a JSP tag library and an Advisor EJB (stateless session bean) that access the WebLogic Portal's core personalization services including:

User Profile Management
Rules Manager
Content Management
Personalization Platform

The tag library and session bean contain personalization logic to access these services, sequence personalization actions, and return personalized content to the application. It is also possible to write your own Advisor plug-ins and access them with JSP tags you create.

This architecture allows the JSP developer to take advantage of the personalization services using the Advisor JSP tags. In addition, a Java developer can access the underlying WebLogic Portal personalization features via the public Advisor bean interface. For more information, see the WebLogic Portal Javadoc API documentation.

You can use the Advisor in one of two ways:

Using the JSP tags. Developers will probably find it easiest to use the JSP tags when building typical pages. The tags provide ways to switch content on and off based on user classification, return content based on a static query, and match content to users based on rules that execute a content query. The JSP tags that perform these tasks are: <pz:div>, <pz:contentSelector>, and <pz:contentQuery>.
Using the Advisor session bean. The page or application developer may use the Advisor session bean directly in place of the tags, if desired. The Advisor session beans provide ways to switch content on and off based on user classification, return content based on a static query, and match content to users based on rules that execute a content query.

Creating a Personalized Portal Application with Advisor JSP Tags

Table 12-1 describes the three JSP tags the Advisor provides to help developers create personalized applications. These tags provide a JSP view to the Advisor session bean and allow developers to write pages that retrieve personalized data without writing Java source code.

Table 12-1 Advisor JSP Tags

Tag	Description
<pz:div>	Turns user-provided content on or off based on the results of a classifier rule being executed. If the result of the classifier rule is true, it turns the content on; if false, it turns the content off.**The system turns on the content by inserting the content residing between the start and end <pz:div> tags in the JSP code. This content can include any valid JSP content, including HTML tags, other JSP tags, and scriptlets. If the classifier rule returns false, the system skips the content between the start and end <pz:div> tags.
<pz:contentQuery>	provides content attribute searching for content in a content management system. It returns an array of Content objects that a developer can handle in numerous ways.
<pz:contentSelector>	recommends content if a user matches the classification part of a content selector rule. When a user matches, the personalization engine executes a content query defined in the rule and returns the content back to the JSP page.

In addition to using JSP tags to create personalized applications, you can work directly with the Advisor bean. For more information about using the bean, see Creating Personalized Applications with the Advisor Session Bean.

Classifying Users with the JSP <pz:div> Tag

The <pz:div> tag to turns user-provided content on or off based on the results of a classifier rule being executed. If the result of the classifier rule is true, it turns the content on; if false, it turns the content off.

Note: Rules are created in the E-Business Control Center. The E-Business Control Center letsusers develop their own classifier rules. Because users are not exposed to the concept of rules, you will see classifier rules referred to as "customer segments."

Listing 12-1 shows how to use the <pz:div> tag to execute the PremierCustomer classifier rule and displays an alert to premier customers in the HTML page's output.

Listing 12-1 Using <pz:dev> to Execute a Classifier Rule

<%@ taglib URI="pz.tld" prefix="pz" %>
.
.
.
<pz:div 
rule="PremierCustomer">
    <p>Please check out our new Premier Customer bonus program</p>
</pz:div>

Selecting Content with the <pz:contentQuery> JSP Tag

Use the <pz:contentQuery> tag to provide content attribute searching of content in a content management system. It returns an array of Content objects that you can handle in numerous ways.

Listing 12-2 shows an example of how to execute a query against the content management system to find all content where the author attribute is Hemingway and then display the Document titles found:

Listing 12-2 Executing a Query Against a CMS to Find Specified Content

<%@ page import="com.bea.p13n.content.ContentHelper"%> 
<%@ taglib URI="pz.tld" prefix="pz" %>
.
.
.
<pz:contentQuery id="docs" contentHome="<%=ContentHelper.DEF_DOCUMENT_MANAGER_HOME %>" query="author = 'Hemingway'" />

<ul>
   <es:forEachInArray array="<%=docs%>" id="aDoc"
   type="com.bea.p13n.content.Content">
      <li>The document title is: <cm:printProperty id="aDoc"
      name="Title" encode="html" />
   </es:forEachInArray>
</ul>

Matching Content to Users with the <pz:contentSelector> JSP Tag

The <pz:contentSelector> recommends content if a user matches the classification part of a content selector rule. When a user matches based on a rule, the Advisor executes the query defined in the rule to retrieve content.

The example in Listing 12-3 asks the Advisor to return content specific to premier customers and then display the Document titles as the results.

Listing 12-3 Asking the Advisor to Display Specific Customers

<%@ page import="com.bea.p13n.content.ContentHelper" %>
<%@ taglib URI="cm.tld" prefix="cm" %>
<%@ taglib URI="pz.tld" prefix="pz" %>
<%@ taglib URI="es.tld" prefix="es" %>
.
.
.
<pz:contentSelector id="docs" 
    rule="PremierCustomerSpotlight"
    contentHome="<%=ContentHelper.DEF_DOCUMENT_MANAGER_HOME %>" />
<ul>
   <es:forEachInArray array="<%=docs%>" id="aDoc"
   type="com.bea.p13n.content.Content">
      <li>The document title is: <cm:printProperty id="aDoc"
      name="Title" encode="html" />
   </es:forEachInArray>
</ul>

Creating Personalized Applications with the Advisor Session Bean

Java developers can work directly against the Advisor bean through a set of APIs to create personalized applications. This process provides an alternative to using the JSP tags to call into the bean.

Note: See the WebLogic Portal Javadoc for more information about using the session bean to create personalized applications.

The following steps provide a general overview of the process involved for an application to get content recommendations from the Advisor.

Look up an instance of the Advisor session bean.
Use the AdvisorFactory's static createAdviceRequest method to create an AdviceRequest object.

Note: You must provide this method with the URI representing the request. The Advisor uses the URI prefix to determine which Advislet to invoke.
Set the required and optional attributes for the AdviceRequest object.
Call the Advisor's getAdvice method.

The Advisor calls the best Advislet to make the recommendation. The Advislet determines the recommendations and the Advisor then passes the resultant Advice object back to the application.

The Advisor uses the Advislet Registry to choose the Advislet to invoke.
The personalized application extracts the recommendation from the Advice object and uses it in the application.

When a personalized application requests advice from the Advisor, the Advisor bean delegates the request to a registered Advislet that can handle the request. The Advisor uses the URI prefix to determine which registered Advislet will receive the advice request. The Advislet then makes the recommendations and returns the Advice object back to the Advisor. This design encapsulates all of the advice logic into the Advislet and allows developers to create custom Advislets for more specialized purposes.

Attribute objects act as parameters for the request. Attribute objects can be set on the AdviceRequest object and are associated with a String object representing the name of the attribute.

Three Advislets are supplied with the system: Classifier Advislet, ContentQuery Advislet and ContentSelector Advislet. Names for the attributes that need to be set on the supplied Advislets are defined as static Strings in the AdviceRequestConstants interface.

Table 12-2 shows the logic the Advisor uses to determine how to map a recommendation request to an Advislet.

Table 12-2 Mapping recommendation requests to an Advislet

Uri Prefix	Inferred Advislet
classifier	Uses a rules-based inference engine to classify a user based on rules written using the Customer Segment tool in the E-Business Control Center.
contentselector	Uses a rules-based inference engine to classify a user. Determines if the user matches the classification. Uses a rules-based inference engine to obtain a content query for the classification. Selects content based on the content query obtained.
contentquery	Performs a content attribute search on a specified content management system.

The following sections demonstrate how to directly access the Advisor to provide the same functionality as that provided by the JSP tags.

Classifying Users with the Advisor Session Bean

For classification requirements beyond what the JSP tags provide, or to use classification in a servlet, use the Advisor EJB directly.

To ask the Advisor for a classification, use this procedure. (See the Javadoc API documentation for API details.)

Note: Unless otherwise indicated, all classes used here reside in the com.bea.p13n.advisor package.

Look up and create an instance of the Advisor session bean. The EJB_REF_NAME constant found in the EJB Advisor Home interface may be used as the JNDI name of the Advisor EJB Home.
Use the AdvisorFactory's static createAdviceRequest method to create an AdviceRequest object. In this case, the URI argument should be "classifier://".
Set the required attributes on the AdviceRequest object (see AdviceRequestConstants). These include:
Call the getAdvice method on the Advisor, supplying the newly created AdviceRequest.
The Advisor returns an instance of Advice. The getResult method is called to obtain the classification object. If a classification object is returned, then the classification is considered to be true. If the return value is null, the classification is considered to be false.

Note: If the optional AdviceRequest parameter RULES_RULENAME_TO_FIRE is not supplied, there may be multiple classifications returned for the user.

Querying a Content Management System with the Advisor Session Bean

For content selection requirements beyond what the JSP tags provide, or to use content selection in a servlet, developers can use the Advisor EJB directly.

To ask the Advisor for a content, use this procedure. (See the Javadoc API documentation for API details.)

Note: Unless otherwise indicated, all classes used here reside in the com.bea.p13n.advisor package.

Look up and create an instance of the Advisor session bean. The EJB_REF_NAME constant found in the EJB Advisor Home interface may be used as the JNDI name of the Advisor EJB Home.
Use the AdvisorFactory's static createAdviceRequest method to create an AdviceRequest object. In this case, the URI argument should be "contentquery://"
Set the required attributes on the AdviceRequest object (see AdviceRequestConstants). These include:
Call the getAdvise method on the Advisor, supplying the newly created AdviceRequest.
The Advisor returns an instance of Advice. The getResult method is called to obtain the array of Content objects representing the results of the content query.

Matching Content to Users with the Advisor Session Bean

For content selection requirements beyond what the JSP tags provide, or to use content selection in a servlet, developers can use the Advisor EJB directly.

To ask the Advisor for a content, use this procedure. (See the Javadoc API documentation for API details.)

Note: Unless otherwise indicated, all classes used here reside in the com.bea.p13n.advisor package.

Look up and create an instance of the Advisor session bean. The EJB_REF_NAME constant found in the EJB Advisor Home interface may be used as the JNDI name of the Advisor EJB Home.
Use the AdvisorFactory's static createAdviceRequest method to create an AdviceRequest object. In this case the URI argument should be "contentselector://"
Set the required attributes on the AdviceRequest object (see AdviceRequestConstants). These include:
Call the getAdvise method on the Advisor, which supplies the newly created AdviceRequest.
The Advisor returns an instance of Advice. The getResult method is called to obtain the array of Content objects representing the recommendation.

Personalizing Applications with HTTP Request and Session Properties

Attributes in the HTTP Request and Session can be used to personalize content. Use the E-Business Control Center to create Customer Segments, Content Selectors, or Campaigns that use HTTP Request and Session property sets. Once you have synchronized your Request or Session property sets to the WebLogic Portal server, you can personalize content with them.

HTTP Request-Based Personalization

This section shows a Customer Segment definition created in the E-Business Control Center. The Customer Segment, called RequestPropertyDemo, automatically makes a user a member of the Customer Segment when an HTTP request has a specific value. The HTTP request value being looked for is defined in an HTTP Request property called RequestPropertyOne, which is also defined in an HTTP Request property set in the E-Business Control Center. If the value of RequestPropertyOne is success, the user is a member of the RequestPropertyDemo Customer Segment and can be targeted with personalized content.

When all of these conditions apply:
an HTTP request has the following properties:
RequestPropertyOne is equal to `success'
Consider the visitor a member of the RequestPropertyDemo segment.

The Customer Segment definition and HTTP Request property definition must be saved and synchronized to the WebLogic Portal server.

The following JSP code does the following:

The request.setAttribute() method sets an HTTP request property, called RequestPropertyOne to a value of success. Because of the Customer Segment definition, this HTTP request value makes the user a member of the RequestPropertyDemo Customer Segment.
The <pz:div> JSP tag has a rule attribute whose value is RequestPropertyDemo, the name of the Customer Segment defined in the E-Business Control Center.
The <pz:div> tag contains the content that is displayed only to members of the RequestPropertyDemo Customer Segment.

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

<%

    request.setAttribute("RequestPropertyOne", "success");

%>

<pz:div rule="RequestPropertyDemo">

    <p>--  the "RequestPropertyDemo" rule evaluated to "true"</p>

</pz:div>

While this example shows personalization based on a user's Customer Segment membership, you can trigger HTTP Request-based personalization directly in Content Selectors and Campaigns. When you define Content Selectors and Campaigns in the E-Business Control Center, you can trigger them with HTTP Request property values without using Customer Segments.

HTTP Session-Based Personalization

Personalization using HTTP Session-based Customer Segments is performed similarly to HTTP Request-based Customer Segments. The following JSP code assumes the E-Business Control Center has been used to create and synchronize a Customer Segment named SessionPropertyDemo and an HTTP Session property called SessionPropertyOne.

The text within the <pz:div> tags will be displayed only to members of the SessionPropertyDemo Customer Segment when the JSP is rendered.

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

<%

    session.setAttribute("SessionPropertyOne", "sessionValue");

%>

<pz:div rule="SessionPropertyDemo">

    <p>--  the "SessionPropertyDemo" rule evaluated to "true"</p>

</pz:div>

While this example shows personalization based on a user's Customer Segment membership, you can trigger HTTP Session-based personalization directly in Content Selectors and Campaigns. When you define Content Selectors and Campaigns in the E-Business Control Center, you can trigger them with HTTP Session property values without using Customer Segments.

Special Considerations

Request and Session attributes are not scoped to specific property sets. For example, you can create a SessionPropertyOne in two different Session property sets, then set an attribute of that name in the HTTP Session, and all rules based on that property will be evaluated without reference to the property set in which it is found.

To extend the previous Session-based example, create a second Session property set, also with a property called SessionPropertyOne, but make it a numeric property. Then create a second Customer Segment called SessionPropertyDemoTwo as follows:

When all of these conditions apply:
the HTTP session has the following properties:
SessionPropertyOne is equal to 3
Consider the visitor a member of the SessionPropertyDemoTwo segment.

The following JSP code contains two <pz:div> tags. One contains content that will be displayed to members of the SessionPropertyDemo Customer Segment, and the other contains content that will be displayed only to members of the SessionPropertyDemoTwo Customer Segment.

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

<%

    session.setAttribute("SessionPropertyOne", new Long(3));

%>

<pz:div rule="SessionPropertyDemo">

    <p>--  the "SessionPropertyDemo" rule evaluated to "true"</p>

</pz:div>

<pz:div rule="SessionPropertyDemoTwo">

    <p>--  the "SessionPropertyDemoTwo" rule evaluated to "true"</p>

</pz:div>

Because of the SessionPropertyOne value in the session.setAttribute() method, whose value defines the SessionPropertyDemoTwo Customer Segment, the rule=SessionPropertyDemoTwo will evaluate to "true," and the rule=SessionPropertyDemo will evaluate to "false", even though the property was defined in two different property sets. Normally this should not be a problem, as duplicate properties are not usually defined in different property sets. However, the E-Business Control Center does not alert you if you do this.

Triggering Campaign Actions with Session, Request, and Event Properties

Campaign scenario rules are evaluated only when a single event occurs for which the campaign listener is configured. When the event is triggered, the event takes a snapshot of the current session properties, the single request property (contained in the session), and the event properties (contained in the request). The snapshot taken by the event is in the form of a Request object, which the event passes to the Campaign service for evaluation. If the values in that snapshot evaluate to true against any Campaign action rules, those Campaign actions are triggered.

When campaign actions are not triggered as expected using session, request, and event properties, one or more of the following is usually to blame:

No event was fired that the Campaign service was listening for.
The session, request, or event properties contained in the Campaign rule were not part of the Request object snapshot taken when the event was fired.
In Campaign rules that are defined so that all conditions must apply for the campaign action to be triggered, one or more of the conditions evaluated to false.

Consider the following Campaign action rules as created in the E-Business Control Center:

When all of these conditions apply:
an HTTP request has the following properties:
RequestPropertyOne is equal to `success'
any of the following events has occurred:
SessionLoginEvent
Do the following [Ad action, e-mail action, or discount action].

The rule will be evaluated only if an event for which the Campaign service is listening occurs. (This event need not be used directly in the Campaign rule.) For example, if the Campaign service is configured to listen for the BEA-provided UserRegistrationEvent (which it is by default), then when a UserRegistrationEvent occurs the event takes a snapshot of the Request object and the Campaign rules are evaluated.

Here is how the previous Campaign action rules would be evaluated:

Is there a request property called RequestPropertyOne with a value of success?
Am I a SessionLoginEvent?
Are all of these conditions true?

Because a UserRegistrationEvent woke up the campaign service and took a snapshot of the request object, the campaign action will not be triggered, because the rule requires that all of its conditions evaluate to true. The SessionLoginEvent rule is false (because it was the UserRegistrationEvent that woke up the campaign service).

If the rule was defined so that any of the conditions evaluating to true would trigger the action (rather than all conditions), the campaign action would have fired if the request property evaluated to true.

To use session or request properties to trigger campaign actions, make sure you do the following:

In the JSP containing the event to be fired, get the request attribute through a variable or set it directly in the JSP.
In the JSP containing the event to be fired, get/set any event properties you want to use.
If you want to use session properties to trigger campaign actions, make sure the firing event is in the same session containing the session properties you want to use.

For more information on events and using them in Campaigns, see Event and Behavior Tracking, in particular Writing the Custom Event Class, which contains information on getting the Request object with your event.

Working with the Rules Framework

Rules Management forms a key part of the personalization process by prescribing a flexible and powerful mechanism for expressing business rules. The business logic encompassed by these rules allows robust delivery of personalized content marketed specifically to each end user type.

The various components of the Rules Framework are configured with an external configuration file called rules.properties. This file resides in the p13n_util.jar file (within the com/bea/p13n/rules directory) that can be found in the root directory of any WebLogic Portal application. This section explains each of the configuration properties that can be set in this file.

Changes to the rules.properties file are only seen by the application in which the file resides. That is, this configuration file is scoped to the application. This makes it possible to configure the Rules Framework differently for different applications.

Validating Rules Expressions

If you want the Rules engine to validate all Rules expressions (both conditions and actions) exactly one time, set rules.engine.expression.validation to true. You can set this property to true during development and testing for additional expression validation, as shown in Listing 12-4.

Listing 12-4 Setting the rules.engine.expression.validation Property

##
# Rules engine expression validation:
#
# If this property is set to true, the rules engine
# will validate expressions the first time they are
# executed.
##
rules.engine.expression.validation=true

Rules Engine Error Handling and Reporting

The rules.engine.throw.expression.exceptions and rules.engine.ignorable.exceptions properties determine the type of exceptions that will be propagated to the user during Rules engine execution.

To prevent exceptions from being propagated and any condition expression that generates an exception to evaluate to false, set the rules.engine.throw.expression.exceptions parameter to false.
To propagate all exceptions to the user—except those listed with the rules.engine.ignorable.exceptions parameter—set the rules.engine.throw.expression.exceptions parameter to true.

Listing 12-5 shows an example of how these parameters are set.

Listing 12-5 Rules Engine Pattern Expression Execution Error Handling

##
# Rules engine pattern expression execution error handling:
#
# rules.engine.throw.expression.exceptions
#
# If this property is set to true, pattern expression
# execution exceptions will be thrown. Otherwise, a pattern
# expression exception will cause the pattern condition to
# evaluate to false.
#
# Defaults to true.
#
# rules.engine.throwable.exceptions (list of class names)
#
# If the previous property is set to true, expression exceptions
# with embedded exceptions of a type other than the listed classes
# will be thrown. If no class types are specified, all expression
# exceptions will be thrown.
#
# Defaults to all exception class types.
##
rules.engine.throw.expression.exceptions=true
rules.engine.ignorable.exceptions=java.lang.NullPointerException

Personalization with Content Selectors

A content selector is one of several mechanisms that WebLogic Portal provides for retrieving documents from a content management system. By using content selectors, you can personalize a portal or portlet by specifying conditions under which WebLogic Portal retrieves one or more documents. For example, you can personalize a portlet that displays data from a content management system by specifying such information as a date range, the status of the user, and the user's e-mail address. The content selector would only retrieve documents that fit the selection criteria.

Note: Before you can work with content selectors, customer segments must be created. Creating segments is an administrative task and is discussed in the Administration Guide. For more information, see "Creating Customer Segments" at http://download.oracle.com/docs/cd/E13218_01/wlp/docs70/admin/usrgrp.htm#1184110.

Use the 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, use the content selector JSP tags and a set of other JSP tags to retrieve and display the content targeted by the content selector.

To use the E-Business Control Center to define the conditions that activate a content selector and the query criteria, use this procedure:

Open the E-Business Control Center and display the Presentation tab.
Click the Content Selector icon in the left pane of the Explorer.

Any existing content selectors will appear in the right pane of the Explorer.
Select New to display the New menu and select Content Selector.
Figure 12-1 E-Business Control Center New Menu with Content Selector Selected

The Content Selector Editor appears.

Figure 12-2 Content Selector Editor
Double-click anywhere on the Selection rule pane to open the Selection Rules editor:
Figure 12-3 Selection Rules Editor
Click the checkbox next to each condition you want to activate the content selector. For each condition selected, a related action is added to the action pane.
Figure 12-4 Selection Rules Editor with Conditions Selected
In the Action pane, do the following:
In the E-Business Control Center, open the File menu and select Save as.

The Save as dialog box appears.

Figure 12-6 Save As Dialog Box
Type the name you want to call the content selector in Name and click Save.

The new content selector will appear in the content selector list in the Explorer.
Open the Tools menu and select Synchronize.

The new content selector is ready to use.

To use the content selector features on a given JSP, you must add calls to the content selector JSP tag and a set of associated tags. For more information, please refer to Using Content-Selector Tags and Associated JSP Tags.

Using an Edit .jsp to Personalize a Portlet

Visitors can personalize portlets by providing the necessary personalization attributes or preferences to an Edit JSP. An Edit JSP is a JSP that collects personalization data and uses it to render a personalized view of requested date.

Enabling a visitor to personalize a portlet by using an Edit JSP is a two-step process:

Step 1. Create the Edit JSP

Create the Edit JSP (or JSPs, if a Webflow is required) as you would any other JSP. You can name it anything you want and give it any appropriate look and feel. The important features of the JSP are those that allow the visitor to enter and retrieve personalized content.

For example:

The Edit JSP for a stock quote portlet might have a text box or boxes into which the visitor can enter stock symbols and an OK or Set button that launches an event that retrieves a quote for the respective symbols.
The Edit JSP for an email portlet might include edit boxes into which the visitor sets a user name and password for retrieving email from a server, which is also specified on the Edit JSP.
The Edit JSP for a portlet that displays columnar data might have checkboxes that let the visitor turn columns on or off and specify sorting preference.

As you can see, there are few restrictions as to what you need to include in an Edit JSP, so long as it meets visitor personalization requirements.

Step 2. Enable Portlet Editing

Next, you need to enable visitors to edit a portlet to add personalization information. To do this, use this procedure:

Start the E-Business Control Center. For instructions on starting the E-Business Control Center see "Starting the E-Business Control Center" in the Administration Guide at http://download.oracle.com/docs/cd/E13218_01/wlp/docs70/admin/admintro.htm#1185814.
In the Explorer window, click the Presentation tab at the bottom of the Explorer window, then click the Portlets icon.
From the list of portlets in the Explorer, double-click the portlet you for which you want to enable editing.

The Portlet Editor appears.
Select Enable Editing, as shown in Figure 12-7.
Figure 12-7 Portlet Editor with Enable Editing Checkbox Selected
Note that by selecting this checkbox, you also enable the edit box below it. In this box, specify the relative URL of the Edit JSP you created.

For more information on using the Portlet Editor, see "Modifying Portlet Characteristics" in the Administration Guide at http://download.oracle.com/docs/cd/E13218_01/wlp/docs70/admin/frmwork.htm#1199768.

Personalizing a Portal or Portlet by Using Placeholders

Placeholders are devices that represent an area in a portal or portlet to which content is provided when certain criteria are met that define what content can appear. A placeholder is a named entity that contains one or more queries. When a visitor requests a JSP that contains a placeholder tag, the placeholder selects a single query to run—usually based upon established rules or customer properties—and generates the HTML that the browser requires to display the results of the query.

This section includes information on the following subjects:

How Placeholders are Used

Placeholders are used primarily in campaigns to direct a visitor's attention to programs, merchandise, or other information in which the visitor's behavior has indicated an interest. For example, an online sporting goods store notices that a visitor has purchased a number of fishing lures from a specific manufacturer. A rule exists that tells the portal to display information about discounts available when the visitor has spent more than a certain amount of money on products by that particular manufacturer. The visitor will see that information in the area specified as the placeholder for that content. Another visitor has shown interest in camping equipment (measured by the number of times that visitor has accessed the "Camping" pages for the sporting goods store's catalog). Instead of fishing lure discounts, the camper will see information about camping gear in the area specified as the placeholder.

The above example demonstrates how ad placeholders are used to personalize information for a specific visitor. In the same manner, non-ad placeholders can offer the same level of personalization. For example, a doctor researching drugs at a pharmaceutical company Website shows a tendency for studying a certain family of drugs. The company's portal can track his behavior and display, in a placeholder, information about, or links to, related drugs that he hasn't yet researched.

Placeholders are created by using a JSP tag and defining the placeholder queries in the E-Business Control Center. This section describes how to use those features to set up placeholders to personalize portal and portlet content.

Placeholder JSP Tag: <ph:placeholder>

The placeholder tag <ph:placeholder> is a named location on a JSP. The tag identifies the placeholder to the JSP and describes the behavior established for it in the E-Business Control Center. See Creating Placeholder Files for instructions on using the E-Business Control Center to set up the placeholder behavior.

Note: In the following tables, the Required column specifies if the attribute is required (yes) or optional (no). In the R/C column, C means that the attribute is a Compile time expression, and R means that the attribute can be either a Request time expression or a Compile time expression.

The <ph:placeholder> tag (Table 12-3) implements a placeholder, which describes the behavior for a location on a JSP page.

Multiple placeholder tags can refer to the same placeholder. Each instance of a placeholder tag invokes its placeholder definition separately. If the placeholder definition specifies multiple queries, each placeholder tag instance can display different ads, even though each instance shares the same definition.

When WebLogic Portal receives a request for a JSP that contains an ad placeholder, the placeholder tag contacts the Ad Service, a session EJB that invokes business logic to determine which ad to display.

Table 12-3 <ph:placeholder>

Tag Attribute	Req'd	Type	Description	R/C
name	Yes	String	A string that refers to a placeholder definition.	R
height	No	int	Specifies the height (in pixels) that the placeholder uses when generating the HTML that the browser requires to display a document. The placeholder uses this value only for content types to which display dimensions apply and only if other attributes have not already defined dimensions for a given document. If you do not specify this value and other attributes have not already been defined, the browser behavior determines the height of the document.	R
width	No	int	Specifies the width (in pixels) that the placeholder uses when generating the HTML that the browser requires to display a document. The placeholder uses this value only for content types to which display dimensions apply and only if other attributes have not already defined dimensions for a given document. If you do not specify this value and other attributes have not already been defined, the browser behavior determines the height of the document.	R

Example

This example displays the ad specified in the MainPageBanner placeholder.

<%@ taglib uri="ph.tld" prefix="ph" %>
. . .
<ph:placeholder name="/placeholders/MainPageBanner.pla"/>

Implementing the Placeholder

To implement a placeholder, use this procedure:

Open the JSP template file that will contain the placeholder. JSPs reside in an applicaton folder under the portlets folder for an individual application; for example:
```
<BEA_HOME>\weblogic700\samples\portal\<PORTAL_DOMAIN>\beaApps\
   <PORTAL_APP>\<PORTAL_APP>\portlets\campaigns
```
Import the tag library by including the following code in the JSP
```
<%@ taglib uri="ph.tld" prefix="ph" %>
```
Add <ph:placeholder> within the JSP element where you want the placeholder to appear. Be sure to specify the placeholder name within the placeholder tag, as shown in Listing 12-6.

Listing 12-6 <ph:placeholder> Tag

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

   <tr>
      <td align="center">
         <ph:placeholder name="PrimaryCampaign"/>
      </td>
   </tr>

</table>

Creating Placeholder Files

Use the E-Business Control Center to define placeholder files that match the placeholders in your site's JSPs. The following procedure shows you how to create a placeholder file in the E-Business Control Center and how to set up default—not campaign—queries in that placeholder.

Note: Before beginning this procedure, you must define attributes for the documents in your content management system

To create a placeholder file:

Start WebLogic Server and open the the E-Business Control Center.
Open the application with which you want to work.
Choose File —> New —> Presentation —> Placeholder. A new placeholder file opens in the Editor window, as shown in Figure 12-8.
Figure 12-8 Placeholder Editor
Enter a description for the placeholder in the Description area.
Click New to begin defining a default query. A placeholder file is considered incomplete if it does not have at least one default query (though you can still save the placeholder file).

Note: Since the content you are trying to access is stored on the server, the Connection Setup window appears. Select an existing connection in the Display Name field, and enter your username and password. You only need to log in once per session when working with placeholders.

You can create multiple default queries by repeating this step.

If you do not create ad queries for default ads, the placeholder will display only ads that are generated by campaign queries. If there are no active campaigns, or if an active campaign contains no ad actions within scenarios to trigger an ad for a specific customer, then the placeholder remains empty to customers.
To change the priority of a default query, click the Display Priority column for the query and select a priority, as shown in Figure 12-8.

The Display Priority determines the likelihood that the query runs relative to the priority of any other queries that are in the placeholder.
To prevent an ad placeholder from using default aqueries if it also contains campaign ad queries, select the option, Do not display default ads if ads placed by a campaign apply.

If you want the placeholder to choose among default and campaign ad queries, select the option, Keep default ads in rotation with ads placed by a campaign. This selection potentially reduces the chance that the placeholder displays a given ad that is part of a campaign.
Save and name the placeholder. Be sure to use the name of a placeholder that already exists or will exist on a JSP.

The new file is displayed in the list of placeholders.