> Interaction Management Guide > Creating a Placeholder

Interaction Management Guide

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Creating a Placeholder

A Placeholder is a predefined location in a JSP that displays a single piece of web content at a time that is dynamically retrieved from the BEA Virtual Content Repository. If more than one content query is registered for a Placeholder, the Placeholder uses predefined queries and logic to determine which query to run and which content item to display. If a content query does not return data, the Placeholder runs another registered query, if there is one. Each query has a priority, or weight that determines the specific content to display.

For example, a Placeholder for a pet store could use a Campaign query to determine if the user is a bird lover and then display a special bird offer, as shown in Figure 7-1.

Figure 7-1 Placeholders can Display Default Content and Campaign Content

Placeholders can Display Default Content and Campaign Content

A Placeholder is made up of two parts:

  1. A Placeholder file you create in WorkSpace Studio
  2. A companion JSP tag that performs the processing

When you create a Placeholder, you select the content to display, choose a query for the Placeholder, and then create the Placeholder itself.

This chapter includes the following sections:

 

Selecting Content for a Placeholder

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:

This section contains the following topics:

Displaying Additional MIME Types in a Placeholder

To display content, Placeholders refer to a document's MIME type and then generate the HTML tags that a browser requires for the specific document type. For example, to display an image-type document, an ad placeholder must generate the <img> tag that a browser requires for images. By default, ad Placeholders can generate the appropriate HTML only for the MIME types listed in the Selecting Content for a Placeholder section for images and other types of files.

WARNING: The <EMBED> tags do not always work correctly in all browsers. The behavior depends on the plug-ins you have configured.

If you are familiar with basic Java programming, you can write classes that enable Placeholders to generate HTML for additional MIME types. A video clip is an example of an additional MIME type.

Perform the following tasks to display additional MIME types in a Placeholder:

  1. Create a utility or EJB project and add the Portal Web Application Services facet to the project. For general instructions, see Creating a Regular Event Class.
  2. Create and compile a Java class to generate HTML.
  3. Register the new class.

Creating and Compiling a Java Class to Generate HTML

To generate the HTML that the browser requires to display the MIME type, use WorkSpace Studio to create a utility or EJB project, add the Portal Web Application Services facet to the project with the web project’s Properties dialog. (You can also add this facet to an existing utility or EJB project that is part of your EAR file.) The next steps is to create a Java class that implements the com.bea.p13n.ad.AdRenderableContentProvider interface. For information on this interface, see the Javadoc.

Registering the New Class

After you save the class in a directory that is in your CLASSPATH, you must notify WebLogic Portal of its existence. You can do this manually or with the Administration Console. Choose Method 1 or Method 2 to add the class to your CLASSPATH.

Method 1

Perform the following steps to manually add the class to your CLASSPATH:

  1. To add the class manually, stop the WebLogic Server.
  2. Create a backup copy of your application's META-INF\wps-config.xml file.
  3. Open the wps-config.xml file in a text editor and find the <AdService> element.
  4. Add the following as a sub-element of <AdService>: 
    5. <AdContentProvider
    Name="MIME-type"
    Provider="YourClass.class"
    Properties="optional-properties-for-your-class"
    >
    </AdContentProvider>

    Provide the following values for the attributes of the AdContentProvider element:

    • Name – The name of the MIME type that you want to support.
    • Provider – The name of the compiled Java file. If you saved the file below a directory that your CLASSPATH environment variable names, you must include the file's path name, starting one directory level below the directory in CLASSPATH.
    • Properties – Any additional properties or parameters want to pass to your object.

      • For example, if you added <PORTAL_APP>/classes to the system CLASSPATH, save your class to support AVI files as <PORTAL_APP>/classes/myclasses/MimeAvi.class. The following code sample shows sample attribute values: 

      <AdContentProvider
      Name="video/x-msvideo" 
      Provider="myclasses.MimeAvi"
      Properties="" 
      >
      </AdContentProvider>
  5. Save your changes to the wps-config.xml file.
  6. Restart the WebLogic Server.

You can also add the class to the CLASSPATH using the steps in Method 2.

Method 2

Rather than manually adding the class to your CLASSPATH and activating the content provider, you can use the Administration Console to perform the following steps:

  1. In Workshop for WebLogic, start the Administration Console by choosing Run > Open Portal Administration Console.
  2. In the Administration Console, choose Configuration & Monitoring > Service Administration.
  3. Select Interaction Management in the Resource Tree and click Ad Service in the Browse tab.
  4. In the Ad Content Providers section, click Add Ad Content Provider.
  5. Enter a Description and a Name for the new content provider. In the Content Provider field, specify the name of the class that generates the HTML elements that the browser requires to display an ad of this MIME type. If you write your own class, it must implement the com.bea.p13n.ad.adRenderableContentProvider interface.
    6. WARNING: The Commerce API is deprecated with WebLogic Portal 10.0. The API is replaced by AquaLogic Commerce Services, which is available as a product separate from WebLogic Portal.
  6. Click Update.
  7. After you add the content provider, you can add additional properties.

Adding Content to a Placeholder

You can add specific properties to content items that support using content in Placeholders. See Setting up Content.

 

Creating a Placeholder

Creating a Placeholder involves two steps:

  1. Create a Placeholder file in WorkSpace Studio.
  2. Use companion <ph:placeholder> JSP tags in any relevant JSPs. See the JSP Tag Javadoc for more information on the Java class.

Each <ph:placeholder> JSP tag must use its name attribute to reference a Placeholder you have created in WorkSpace Studio.

This section contains the following topics:

Creating a Placeholder File

A Placeholder is a predefined location in a JSP that displays a single piece of web content retrieved from the BEA Virtual Content Repository. A Placeholder uses queries to retrieve and display content.

By default, Placeholders support the following MIME types: HTML, XML, plain text, and images. To display additional MIME types in Placeholders, see Displaying Additional MIME Types in a Placeholder.

Content returned from a Placeholder is displayed in a portlet. When a user views a portlet or a portal desktop containing a Placeholder, the Placeholder's rules and back-end logic run a query, retrieve zero or more pieces of content matching the query, and display one of the returned items. If no content is retrieved, none is displayed.

The queries for a Placeholder originate from two different locations:

Because a Placeholder can contain multiple queries, the Placeholder can display a different piece of content each time a user accesses the JSP containing the Placeholder. The following procedure includes a step that lets you set a query's priority to increase or decrease the chances that the query is run instead of other queries present in the Placeholder.

Placeholders are scoped to the enterprise application, so you can include Placeholders in any JSPs within the enterprise application.

Note: The steps in this chapter refer to the data\src folder in the Package Explorer View. Your data and src directories might be named differently.

Perform the following steps to create a Placeholder:

  1. Start the WebLogic Server in Workshop for WebLogic by choosing Run As > Run on Server. For instructions on configuring the WebLogic Server, see the Portal Development Guide.
  2. In the Portal Perspective, right-click the <data>\src\placeholders folder in the Package Explorer View and choose New > Content Placeholder.
  3. In the New Placeholder File window, enter a name for the Placeholder in the File name field. Keep the .pla file extension.
  4. Click Finish. The Placeholder Editor appears.
  5. In the Design Palette tab, drag the New Query into the Placeholder Editor to define a default query, as shown in Figure 7-2.
    6. Figure 7-2 Define a Default Query by Dragging the New Query into the Placeholder Editor


    Define a Default Query by Dragging the New Query into the Placeholder Editor

    Every query you add to the Placeholder in this way is a default query (non-Campaign). Campaigns can also put queries in this Placeholder, but Campaign queries are not defined in the Placeholders themselves. They are defined in the Campaigns.

    Note: If you do not see the Design Palette tab, click Show List to see other tabs that are not visible, as shown in Figure 7-3.
    Figure 7-3 Click Show List to View Hidden Tabs
    Define a Default Query by Dragging the New Query into the Placeholder Editor
  6. In the Property Editor window, set values for the following:
    • Name – Enter a name for the query. The query name is used only for display purposes.
    • Priority – Select the query’s priority relative to other queries. A query with a higher priority is more likely to be run.
  7. To define the query, click the empty content search link in the New Query item you added. You can define the query using WebLogic Portal's expression syntax (on the Advanced tab) or in graphical mode (on the Query tab).
    • Advanced Mode – In the Content Search window, click the Advanced tab and build a query using the instructions in Building a Content Query with Expressions.
    • Graphical Mode – Begin with Step a and build a content query by selecting content properties, comparators, and values to retrieve content items.
    1. In the Content Search window, select the Query tab.
    2. Select a content type in the Property set field, select a content property in the Property field, and click Add as shown in Figure 7-4. This example shows a content type of ad and a property of adTargetUrl. The adTargetUrl property makes an image clickable and provides a target for the clickthrough, expressed as a URL. See the Content Management Guide for more information.
      3. Figure 7-4 Choose a Content Type and a Content Property


      Choose a Content Type and a Content Property

      Note: The properties you select are content properties (types) rather than property set properties, such as User Profile or session properties.
    3. In the Content Search Values window that appears, select one of the following tabs:
    • Values Tab – Define the query based on a comparison to a value you enter. For example, the query could be set to retrieve content with an investorRiskLevel property that is marked as high. The example in Figure 7-5 sets the query to retrieve an adTargetUrl of a BEA web site.
    • Properties Tab – To define the content query based on the property value that is dynamically obtained from another type of property, such as a User Profile property. For example, instead of creating a query based on static content properties, you can create a query that reads the value of the current user's investorRiskLevel to populate the query. The query would be different for each user.
      • Figure 7-5 Select an Item for the Comparison Field and Enter a Value


      Select an Item for the Comparison Field and Enter a Value

    1. Click Add. The query descriptor is added to the Value Phrases section.
    2. You can add more value phrases to the query and then set the appropriate option in the For multiple value phrases section at the bottom of the window.
  8. Click OK in the Content Search Values window.
  9. Create additional queries as needed in the Content Search window. You can add more value phrases to the query in the Content Search window, and then set the appropriate option in the For multiple descriptors section at the bottom of the window. Click OK when you are done.
  10. Click OK on the Content Search dialog.
  11. You can preview the content that will be retrieved by the query by selecting the Content Preview tab below the Editor. If you defined the query to use values from a User Profile property, the retrieved content will be different for each user, so you must enter the username of an existing user, such as weblogic, in the Preview User field to see the content that will be retrieved for that user.

    The Content Preview window shows content that the query will retrieve. However, since a Placeholder can show only one piece of content at a time, the single piece of content that is displayed varies depending on which query is run (determined by the priority you set for a query and the settings for Campaign queries) and the adWeight property setting on content.

    You must add the adWeight property to a content type as a single-value Integer. Content with a higher adWeight number has a higher likelihood of being selected for display in a Placeholder.
  12. Save the Placeholder file.
  13. Add the Placeholder JSP tag called <ph:placeholder> to the relevant JSP. You must add the Placeholder filename to the Placeholder tag and run the JSP to see the results.
Note: An alternative to using Placeholders is using the <ad:adTarget> JSP tag to hard-code a content query within the tag. See Using the <ad:adTarget> Tag Instead of a Placeholder for more information.

Choosing the Type of Placeholder Query to Run

Placeholders can run two types of queries: default queries and Campaign queries.

Both types of queries have the same structure but originate from different places:

Figure 7-6 shows the location on a page where the Placeholder displays 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 which query to run and then which retrieved content item to display.

Figure 7-6 Placeholders can Display Default Content or Campaign Content

Placeholders can Display Default Content or Campaign Content

Building a Content Query

You can use the WebLogic Portal Expression language in WorkSpace Studio to build content queries. The advanced query-building window is available from content-related JSP tags and when building queries for Placeholders, Campaigns, and Content Selectors.

If more than one content query is registered for a Placeholder, for example, the Placeholder uses predefined queries and logic to determine which query to run and which content item to display. If a content query does not return data, the Placeholder runs another registered query, if there is one. Each query has a priority, or weight that determines the specific content to display.

A query contains three parts: <property> <comparator> <value>.

Using Expressions

The following two types of properties are available for content, and you can use both in queries:

See Building a Content Query with Expressions for instructions and a list of explicit content properties.

Using Comparators

Comparators provide the logic that compares a query's property to the value you enter. If a content item meets the conditions of the query, the content item is returned. See Using Comparators for instructions.

Using Values

Values represent the content you want the query to return. By supplying values to a query, you're telling the query which content to retrieve (or ignore) based on the values stored on the content items. See Supplying Values for instructions.

Following Guidelines for Complex Queries

You can combine multiple independent query clauses, tying them together with and (&&) and or (||) logic and controlling the order of evaluation with parentheses the way you would with algebraic expressions. This lets you create more complex queries. See the Content Management Guide for instructions and a list of example queries.

Determining Which Query and Content to Display

Placeholders perform a two-step process to choose which content to display. This section describes the following tasks:

  1. How a Placeholder chooses which query to run
  2. Once a query runs, how a Placeholder chooses which content item to display from the query

Choosing a Query to Run

When you add a default query to a Placeholder or create a Campaign query in WorkSpace Studio, 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 instructions, see Modifying a Placeholder.

Choosing 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 Determining Content Priority .

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

Adding a Placeholder to a JSP

After you create a Placeholder file in WorkSpace Studio, you can use any of the following methods to add the Placeholder to a JSP in WorkSpace Studio:

 

Modifying a Placeholder

You can use either of the following two ways to modify a Placeholder:

See Managing Placeholders for Optimal Performance for information on changing Placeholders to improve performance.

 

Using the <ad:adTarget> Tag 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. You can also use <pz:contentQuery> and <cm:search> tags to execute runtime queries and return content that can be displayed.

Tip: You can get rotating banner-style content on your portal by picking one content item and cycle through the matching items on subsequent requests. You can use the <ad:adTarget> JSP tag, which uses the AdConflictResolver to pick which content to show. That will get each node's adWeight property (converted to a number) as the relative weight of each node and then use a random number to pick which content to use. The higher the weight, the more likely the content is to be displayed. If the item doesn't have an adWeight property, it assumes a value of 1.

For more information on the class for the <ad:adTarget> JSP tag, see the JSP Tag Javadoc.

The following code sample shows how to set up rotating banner-style content: 

<%@ taglib uri="http://www.bea.com/servers/portal/tags/ad" prefix="ad"%>
<ad:adTarget query=" color == userProperty('GeneralInfo', 'FavoriteColor') "/>

  Back to Top       Previous  Next