Working with Ad Placeholders

An ad placeholder 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 content as documents in a content management system because it offers an effective way to store and manage information.)

Ad placeholders are intended to display documents that advertise products or services (ads) and to record customer reactions to them. You can use a single set of ad placeholders to support multiple advertising projects that change over time. If you use Campaign Manager for WebLogic, you can use ad placeholders to display ads for campaigns.

A Business Analyst (BA) uses the BEA E-Business Control Center to define the behavior of an ad placeholder. Then, a Commerce Business Engineer (CBE) creates ad placeholder JSP tags in JSPs.

Similar to ad placeholders, the <ad:adTarget> JSP tag also provides services for displaying ads. However, as described later in this topic, the <ad:adTarget> JSP tag provides a subset of the ad placeholder services.

This topic includes the following sections:

What Are Ad Placeholders, Ad Attributes, and Placeholder Tags?

This section describes the following items:

Ad Placeholders

An ad placeholder is a named entity that contains one or more queries. When a customer requests a JSP that contains an ad placeholder tag, the placeholder selects a single ad query to run and generates the HTML that the browser requires to display the results of the query.

For example, you want to display ads in the top banner of your Web site's home page. You define an ad placeholder and create ad queries for the placeholder. Then you create an ad placeholder JSP tag in the top banner of the home page. When a customer requests the home page, the placeholder selects a query, runs the query, and displays the results in the banner.

This section includes the following subsections:

Types of Queries That Ad Placeholders Run

Ad placeholders can run a default query or a query that is associated with a specific scenario in a campaign.

You create default ad queries when you define the ad placeholder in the E-Business Control Center. A placeholder runs a default query each time a customer loads a page that includes the placeholder. For example, you define a default query for a top banner placeholder and the placeholder runs the query each time a customer loads a page with the top banner.

You create scenario queries when you define scenario actions in the E-Business Control Center. (Scenario actions, which are available only with Campaign Manager for WebLogic, specify a list of actions to take in response to a chain of events.) A placeholder contains a scenario query only if a customer or an event triggers the scenario action. For example, you create a scenario that does the following:
When a customer places a handsaw product in the shopping cart, the scenario places an ad for miter boxes in the ad placeholder on the shopping cart page. When the customer requests the shopping cart page, the shopping cart ad placeholder runs the query for miter box ads and displays the results.

Types of Documents That Ad Placeholders Display

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

Ad Attributes in the Content Management System

Ad placeholders use a set of document attributes that you define in your content management system to support the following features:

Table 1-1 Attributes for All Document Types

Table 1-2 Attributes for Image Files

For more information about these attributes, refer to your Shockwave developer documentation.

Table 1-3 Attributes for Shockwave Files

Attribute Name	Value Type	Description and Recommendations
swfLoop	String	Specifies whether the movie repeats indefinitely (true) or stops when it reaches the last frame (false). Valid values are true or false. If you do not define this attribute, the default value is true.
swfQuality	String	Determines the quality of visual image. Lower qualities can result in faster playback times, depending on the client's Internet connection. Valid values are low, high, autolow, autohigh, best.
swfPlay	String	Specifies whether the movie begins playing immediately on loading in the browser. Valid values are true or false. If you do not define this attribute, the default value is true.
swfBGColor	String	Specifies the background color of the movie. This attribute does not affect the background color of the HTML page. Valid value syntax is #RRGGBB.
swfScale	String	Determines the dimensions of the movie in relation to the area that the HTML page defines for the movie. Valid values are showall, noborder, exact fit.
swfAlign	String	Determines whether the movie aligns with the center, left, top, right, or bottom of the browser window. If you do not specify a value, the movie is aligned in the center of the browser. Valid values are l, t, r, b.
swfSAlign	String	Determines the movie's alignment in relation to the browser window. Valid values are l, t, r, b, tl, tr, bl, br.
swfBase	String	Specifies the directory or URL used to resolve relative pathnames in the movie. Valid values are .(period), directory-name, URL.
swfMenu	String	Determines whether the movie player displays the full menu. Valid values are true or false.

Ad Placeholder JSP Tags

Figure 1-19 Multiple Tags Using a Single Definition

The <ad:adTarget> JSP tag is an additional mechanism for selecting and displaying ads. Use <ad:adTarget> if it is essential that a specific query run in a specific location.

Like an ad placeholder, <ad:adTarget> can do the following:

However, the <ad:adTarget> is unlike ad placeholders in the following ways:

Resolving Ad Query Conflicts

A placeholder can contain many ad queries: you can define multiple default queries and if you use Campaign Manager for WebLogic, multiple scenarios can send queries to a placeholder. To determine which ad query to run, a placeholder uses the Ad Conflict Resolver.

In addition, an ad query can return multiple documents. To determine which ad to display, a placeholder uses the adWeight document attribute.

This section includes the following subsections:

How Ad Placeholders Contain Multiple Queries

Figure 1-20 Different Ad Queries for Different Customers

When the Bronze Customer Pat Gomes logs in and accesses the portlet, WebLogic Personalization Server adds queries for handsaws (which applies to all customers) and electric drills (which applies to Bronze Customers) to ad placeholder L. Then it uses the Ad Conflict Resolver to determine which ad query to run.

How the Ad Conflict Resolver Chooses a Query

When you define an ad placeholder in the E-Business Control Center, you can assign a priority to the default ad queries; when you define scenario actions that specify ad queries, you can assign a priority to the scenario's ad query. The priority affects the probability that an ad query will run relative to other ad queries in the placeholder.

For example, ad placeholder L contains three ad queries:

The total number of points in ad placeholder L is 4. To determine which of the three ad queries to run, the Ad Conflict Resolver does the following:

If the campaign associated with ad query X ends, then the total number of points in ad placeholder L is reduced to 2. To determine which ad query to run, the Ad Conflict Resolver does the following:

How an Ad Placeholder Chooses from Ad Query Results

Depending on how broadly you define an ad query and on the number of documents in your content management system, an ad query could return multiple documents. In your content management system, you can add the adWeight attribute to documents that display as ads.

If a placeholder or <ad:adTarget> query returns multiple documents, the ad placeholder or the <ad:adTarget> tag does the following:

Creating Ad Placeholder Tags

After a BA uses the E-Business Control Center to create ad placeholders, a CBE creates ad placeholder tags in the Web site's JSPs. The placeholder definition determines the behavior of the placeholder tag.

You can create placeholders in JSPs that directly display content to a customer (for example, index.jsp) or in JSPs that are included in other JSPs (for example, heading.jsp).

To Create an Ad Placeholder Tag

All JSP files in the e-commerce sample Web application include heading.inc to create consistency in the top banner. Instead of requiring that the banner on each page use the same placeholder, the placeholder in heading.inc uses a scriptlet to determine the value of the name attribute. A JSP can use the default value for the name attribute (which is cs_top_generic), or it can define a variable named banner and specify a placeholder name as the value for the variable.

Listing 1-1 Using a Scriptlet for the Placeholder Name

<% 

   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">
  <img src="<%=WebflowJSPHelper.createGIFURL(request, response,  
  "/commerce/images/header_logo.gif")%>" width="147" height="108"></td>

  <td colspan="7" height="75" align="center" valign="middle">

<ph:placeholder name="<%= banner %>" />

</td>

Figure 1-22 Placeholder in the E-Commerce JSP Templates

Supporting Additional MIME Types

To display an ad, 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 following MIME types:

If you are familiar with basic Java programming, you can write classes that enable placeholders to generate HTML for additional MIME types. To support additional MIME types, you must complete the following tasks:

Add the New Type to the Deployment Descriptor

Each Campaign Manager for WebLogic Web application must specify its deployment requirements in an XML file called a deployment descriptor. To add a new MIME type for ad placeholders, you must modify the deployment descriptor for your WebLogic Personalization Server Web application. You can use a text editor to modify the deployment descriptor.

If you use the example portal as a framework for developing your own Web application, then the deployment descriptor is located at the following pathname:

$WL_COMMERCE_HOME/config/wlcsDomain/applications/wlcsApp/exampleportal/WEB-INF/web.xml

where $WL_COMMERCE_HOME is the location in which you installed Campaign Manager for WebLogic. Your Web application might be in another location. Contact your Campaign Manager for WebLogic administrator for information on which deployment descriptor to modify.

Listing 1-2 MIME Mapping in exampleportal/WEB-INF/web.xml

<mime-mapping>

    <extension>
      jpeg
    </extension>

    <mime-type>
      image/jpeg
    </mime-type>

</mime-mapping>

To add a new mapping, use the following syntax:

<mime-mapping>

    <extension>
      file-extension
    </extension>

    <mime-type>
      type/subtype
    </mime-type>

</mime-mapping>

where file-extension is the extension of the file type you want to map and type/subtype is a recognized MIME type and subtype.

Make sure that you provide end-tags for each of the XML elements.

Create and Compile a Java Class to Generate HTML

Register the New Class in weblogiccommerce.properties

After you save the class in a directory that is in your classpath, you must notify Campaign Manager for WebLogic of its existence and purpose by adding a line to weblogiccommerce.properties. You can use a text editor to modify this file, which is located at the following pathname:

$WL_COMMERCE_HOME/weblogiccommerce.properties

where $WL_COMMERCE_HOME is the location in which you installed Campaign Manager for WebLogic.

adtargettag.rendering.mime-type.mime-extension=your-classname

Provide the following values for the variables in the previous syntax statement:

For example, $WL_COMMERCE_HOME/classes is in the classpath. You saved your class to support AVI files as
$WL_COMMERCE_HOME/classes/myclasses/MimeAvi.class
To register your classname, add the following line to weblogiccommerce.properties:

adtargettag.rendering.video.avi=myclasses.MimeAvi

Listing 1-3 Rendering Classes in weblogiccommerce.properties

###############################################

# AdTargetTag Properties

adtargettag.rendering=com.bea.commerce.platform.ad.AdClickThruServlet
# This is the class that implements the AdEventTracker interface
# and is used to raise events
adtargettag.eventtracking=com.bea.commerce.campaign.AdTracking

# Additional classes to render content based upon mime type
# To use replace the "text.html" with the mime type, replacing any
# '/' characters with '.'

# Place the name of the java class that handles the mime type after the '='

#adtargettag.rendering.text.html=

How Placeholders Select and Display Ads