Interaction Management Guide

Placeholders

Placeholders display a single content item on a JSP—a content item dynamically retrieved from BEA's Virtual Content Repository. A placeholder retrieves content using predefined queries that are put in the placeholder.

Think of a placeholder as a bucket that holds queries, runs one query at a time, and displays one of the content items retrieved by the query. A placeholder is made up of two parts: a placeholder file you create in WebLogic Workshop and a companion JSP tag that performs the processing.

In Figure 4-1, the placeholder file is called "foo", and the JSP tag references the placeholder file.

Figure 4-1 The two parts of a placeholder: a placeholder file and a JSP tag

The two parts of a placeholder: a placeholder file and a JSP tag

This chapter describes how queries are put in placeholders and how the placeholder decides which query to run and which content item to display.

This chapter includes the following sections:

Queries that Placeholders Run

Placeholders can run two types of queries: default queries and campaign queries. Both types of queries have the exact same structure but come from different places.

Default queries - When you create a placeholder file in WebLogic Workshop, you can also add one or more queries to that placeholder file that always stay with the placeholder (unless you change or remove the queries in WebLogic Workshop). These are default queries. They return content from the Virtual Content Repository regardless of who is viewing the portlet or JSP in your portal. Creating a default query for a placeholder is a best practice, because it ensures that no matter what, a content item will always appear in the placeholder.

A placeholder can run a default query each time a user loads a page that includes the placeholder. For example, you define a header for a particular shell that contains a JSP file with a placeholder. If that placeholder contains a default query, a user is likely to see different content in the header each time the user visits or refreshes the desktop.

Campaign queries - When you create a campaign in WebLogic Workshop, one of the things you may most often want to do is trigger campaign-specific content to appear in a specific place on the desktop. Campaigns use placeholders to display personalized content. When you define a content action in a campaign, one of the steps is to select an existing placeholder to run the campaign query you define. Campaign content queries are dynamically placed by a campaign when a certain actions (events) occur, such as a user logging in to the desktop who belongs to a certain user segment.

You can set default queries to not run when a query placed by a campaign is present in the placeholder.

Figure 4-2 shows the location on a page where the placeholder will display an image, either from a default query or a campaign query. The image is retrieved from BEA's Virtual Content Repository through a query. A placeholder uses different factors to determine, first, which of its queries to run, and then which of the retrieved content items to display.

Figure 4-2 Placeholders can display default content and campaign content

Placeholders can display default content and campaign content

Types of Content Placeholders Can Display

Placeholders use a document's MIME-type attribute to generate the appropriate HTML tags that the browser requires. By default, placeholders generate the appropriate HTML tags only for the following MIME types:

Images - For this type of document, a placeholder generates an <img> tag with attributes that the browser needs to display the image. If you want images to be clickable, you must specify the target URL and other link-related information as ad attributes in your content management system.
Shockwave files - For this type of document, a placeholder generates the <OBJECT> tag, which Microsoft Internet Explorer on Windows uses to display the file, and the <EMBED> tag, which browsers that support the Netscape-compatible plug-in used to display the file. In your content management system, you can specify attributes for the <OBJECT> and <EMBED> tags.
XHTML (a fragment or an entire document). For this type of document, a placeholder passes the text directly to the JSP.

If you want to use additional MIME types in placeholders, 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 Placeholders

There are specific properties you can add to content items to better support the use of content in placeholders. See Setting up Content in this guide.

Creating Placeholders

Creating a placeholder involves creating a placeholder file in WebLogic Workshop and using companion <ph:placeholder> JSP tags in any relevant JSPs. Each <ph:placeholder> JSP tag must use its "name" attribute to reference a placeholder you have created in WebLogic Workshop.

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

"Creating Placeholders" at http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/portal/buildportals/createPlaceholders.html.
"<ph:placeholder> Tag" at http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/portal/taglib/www.bea.com/servers/portal/tags/placeholder/placeholder.html.

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 Placeholders to JSPs

After you create a placeholder file in WebLogic Workshop, you can add the placeholder 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 placeholder. The JSP file contains the placeholder JSP tag with the "name" attribute automatically populated with the name of the placeholder. The include statement for the tag library is automatically added.

Open the JSP to which you want to add the placeholder, and drag the placeholder file from the Application window into the JSP in either Design View or Source View. The JSP tag is added automatically, the "name" attribute is automatically populated with the name of the placeholder, and the tag library include statement is added automatically. See Figure 4-1.
Drag the <ph:placeholder> JSP tag from the Palette window (the Portal Content Placeholder category) into an open JSP and populate the tag's "name" attribute manually. The tag library include statement is added automatically.

How Placeholders Choose Which Query and Which Content

Placeholders go through a two-step process in choosing which content to display. This section describes:

How a placeholder chooses which query to run.

Once a query has run, how a placeholder chooses which content item to display from the query.

1. How a Placeholder Chooses a Query

When you add a default query to a placeholder or create a campaign query in WebLogic Workshop, you can assign each query a "priority": highest, high, normal, low, or lowest. The higher the priority, the higher the likelihood that the query will be run instead of other queries.

If a query does not find any documents, the placeholder chooses another query and runs it.

You can also define default queries so that they do not run when campaign queries are present. For more information, see Combining Default Queries and Campaign Queries in Placeholders.

2. How a Placeholder Chooses Which Content Item to Display

Depending on how broadly you define a query and on the number of documents in your content management system, a query could return multiple content items. By default, a placeholder randomly selects a content item to display. To make this selection less of a random choice, you can add a property called adWeight to your content items, as described in Setting up Content in this guide.

The higher the adWeight number you assign to a content item, the higher the likelihood that the content item will be displayed in a placeholder when the content item is retrieved by a query.

Combining Default Queries and Campaign Queries in Placeholders

Placeholders can often become crowded with many queries, especially if more than one campaign uses a placeholder to display content. Campaign queries can remain in placeholders indefinitely unless something specific occurs to remove them. This section describes techniques you can use to clear out unwanted queries and better control the content that is displayed in a placeholder.

When you create default queries in a placeholder, you can designate that default queries do not run when a placeholder contains campaign queries. In WebLogic Workshop, open a placeholder file and select the default query. In the Property Editor window, set the Mix Globals property "false". This suppresses default queries when campaign queries are present.
When you create a content action in a campaign, use the "Remove (all) existing content" option to minimize the number of queries held in a placeholder at a given time.
For campaign content actions, set the duration (time to live) to an appropriate time so that the content action stops putting queries in the placeholder when you want it to stop.
To more accurately control the campaign content that is displayed in a placeholder, create a content action for each event that occurs. Use the previous recommendations to display a fresh rotation of content in the placeholder.
To clear any content that has been put in a placeholder, reset the previously placed content / ad buckets using the reset feature as described in "Resetting Campaigns" in the Campaigns chapter of this guide.

Using <ad:adTarget> Instead of a Placeholder

You can also use the <ad:adTarget> JSP tag to display a content item on a JSP. This tag does not rely on a definition file like a placeholder does. You simply add a query using the tag's "query" attribute. The query retrieves one or more content items (the same types of content items that placeholders can display), and the tag chooses which content item to display in the same manner as the <ph:placeholder> tag. Campaigns do not put queries into an <ad:adTarget> tag, so the tag cannot display personalized content.

For information on building queries, 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.

See "<ad:adTarget> 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/ad/adTarget.html.