Working with Ad Placeholders

 

An ad placeholder is one of several mechanisms that WebLogic Portal 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 WebLogic Portal, 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 Business Engineer (BE) 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?

• Resolving Ad Query Conflicts

• Creating Ad Placeholder Tags

• Supporting Additional MIME Types

• How Placeholders Select and Display Ads

• How to Configure Ad Placeholders in an Application

To learn more about using a content management system with WebLogic Portal, refer to Creating and Managing Content, in this guide. For a comparison of content retrieval methods available with WebLogic Portal, refer to Methods for Retrieving and Displaying Documents.

 

---

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

This section describes the following items:

• Ad Placeholders

• Ad Attributes in the Content Management System

• Ad Placeholder JSP Tags

• The <ad:adTarget> JSP Tag

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

• Types of Documents That Ad Placeholders Display

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 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.

You can prevent a placeholder from running default queries if any scenario actions have specified a query for the placeholder, or you can allow the Ad Conflict Resolver to choose a default query or a scenario query. For more information, refer to Resolving Ad Query Conflicts in this guide.

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:

• XHTML (a fragment or an entire document). For this type of document, a placeholder passes the text directly to the JSP.

• 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.

For information on setting up placeholders to support additional MIME types, refer to Supporting Additional MIME Types in this guide.

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:

• Choosing a single document if a query returns multiple documents

• Making an image ad clickable

• Supplying movie preferences for a Shockwave file

For information about associating attributes with documents, refer to the documentation for your content management system. If you use the reference BulkLoader, refer to Creating and Managing Content, in this guide.

Table 10-20 describes the adWeight attribute, which you can associate with XHTML, image, and Shockwave documents.

Table 10-20 Attributes for All Document Types

Attribute Name	Value Type	Description and Recommendations
adWeight	Integer	Provides an integer that is used to select a document if a query returns multiple documents. Assign a high number to ads that you want to have a greater chance of being selected. For more information, refer to How an Ad Placeholder Chooses from Ad Query Results in this guide. The default value for this attribute is 1. Note: In the E-Business Control Center, you can assign a priority to a query for a scenario action. The priority, which bears no relation to the adWeight attribute, gives a greater or lesser chance that a placeholder runs a query. The adWeight attribute is used to choose an ad after a query has run. For more information, refer to How the Ad Conflict Resolver Chooses a Query in this guide.

 

Table 10-21 describes attributes in addition to the adWeight attribute that you can associate with image files.

Table 10-21 Attributes for Image Files

Attribute Name	Value Type	Description and Recommendations
adTargetUrl	String	Makes an image clickable and provides a target for the clickthrough, expressed as a URL. The Events Service records the clickthrough. Use either adTargetUrl, adTargetContent, or adMapName, depending on how you want to identify the destination of the ad clickthrough.
adTargetContent	String	Makes an image clickable and provides a target for the clickthrough, expressed as the content management system's content ID. The Events Service records the clickthrough. Use either adTargetUrl, adTargetContent, or adMapName, depending on how you want to identify the destination of the ad clickthrough.
adMapName	String	Makes an image clickable, using an image map to specify one or more targets. The value for this attribute is used in two locations: In the anchor tag that makes the image clickable, <a href=value> <img> </a> In the map definition, <map name=value> Use either adTargetUrl, adTargetContent, or adMapName, depending on how you want to identify the destination of the ad clickthrough. If you specify a value for adMapName, you must also specify a value for adMap.
adMap	String	Supplies the XHTML definition of an image map. If you specify a value for adMap, you must also specify a value for adMapName.
adWinTarget	String	Displays the target in a new pop-up window, using JavaScript to define the pop-up window. The only value supported for this attribute is newwindow.
adWinClose	String	Specifies the name of a link that closes a pop-up window. The link appears at the end of the window content. For example, if you provide "Close this window" as the value for this attribute, then "Close this window" appears as a hyperlink in the last line of the pop-up window. If a customer clicks the link, the window closes.
adAltText	String	Specifies a text string for the alt attribute of the <img> tag. If you do not include this attribute, the <img> tag does not specify an alt attribute.
adBorder	Integer	Specifies the value for the border attribute of the <img> tag. If you do not include this attribute, the border attribute is given a value of "0".

 

Table 10-22 describes attributes in addition to the adWeight attribute that you can associate with Shockwave files. Ad placeholders and the <ad:adTarget> tag format these values as attributes of 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.

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

Table 10-22 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

An ad placeholder JSP tag refers to the placeholder definition that you create in the E-Business Control Center. Then it displays the results of the query that the placeholder runs. You can create multiple placeholder tags that refer to a single placeholder definition. (See Figure 10-1.)

For more information about placeholder tags, refer to <ph:placeholder> in Personalization Server JSP Tag Library Reference, in this guide.

Figure 10-1 Multiple Tags Using a Single Definition

 

The <ad:adTarget> JSP Tag

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:

• Generate the HTML that a browser requires to display the types of documents that are described in Types of Documents That Ad Placeholders Display.

• Use the document attributes that are described in Ad Attributes in the Content Management System.

• Use the Ad Service to choose an ad if a query returns multiple documents, as described in How an Ad Placeholder Chooses from Ad Query Results.

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

• It contains its own query; it does not refer to a definition that a BA creates in the E-Business Control Center. If you want to change the query, you modify the tag in the JSP.

• A campaign scenario cannot specify a query to run in an <ad:adTarget> tag. Scenarios can only use ad placeholders to run queries.

• Because it contains only a single query, it does not need to use the Ad Conflict Resolver as described in How the Ad Conflict Resolver Chooses a Query.

For a more information about <ad:adTarget>, refer to Personalization Server JSP Tag Library Reference, in this guide.

 

---

Resolving Ad Query Conflicts

A placeholder can contain many ad queries: you can define multiple default queries and 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

• How the Ad Conflict Resolver Chooses a Query

• How an Ad Placeholder Chooses from Ad Query Results

If you need to make sure that a given ad query runs in a specific location, use an <ad:adTarget> tag, which can contain only a single query. For more information, refer to The <ad:adTarget> JSP Tag in this guide.

How Ad Placeholders Contain Multiple Queries

In addition to containing default queries, an ad placeholder can contain queries that scenarios define. Depending on customers' profiles and the events that customers trigger, a placeholder can contain different queries for different customers. (See Figure 10-2.)

Figure 10-2 Different Ad Queries for Different Customers

 

For example, you create placeholder L at the top of a portlet to display ads for any of the following products:

• Handsaws and miter boxes. You want ads for handsaws and miter boxes to display for any customer, anonymous or authenticated. When you define placeholder L, you include default queries for ads about handsaws and miter boxes.

• Electric drills. You want ads for electric drills, which are part of the Hardware 2001 campaign, to display when a Bronze Customer or Gold Customer logs in. When you define the Hardware 2001 campaign, you include a scenario that places ad queries for electric drills in placeholder L when a Bronze Customer or Gold Customer logs in.

• Circular saws. You want ads for circular saws, which are part of the Hardware 2001 campaign, to display when a Gold Customer logs in. When you define the Hardware 2001 campaign, you define a scenario that recognizes when a Gold Customer logs in. For that scenario, you specify an action that places ad queries for pneumatic hammers in placeholder L.

When the Bronze Customer Pat Gomes logs in and accesses the portlet, WebLogic Portal 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:

• Campaign Ad query X, which has a medium priority. The Ad Conflict Resolver gives all medium-priority ads 2 points

• Default Ad Y, which has a low priority and receives 1 point

• Default Ad Z, which also has a low priority and receives 1 point

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:

1. It creates 4 slots in the ad placeholder. The number of slots corresponds to the total number of points currently in the ad placeholder.

2. It places campaign ad query X, which has 2 points into 2 slots. Each of the other ad queries, with 1 point, gets a single slot:

   1. Slot 1 = campaign ad query X

   2. Slot 2 = campaign ad query X

   3. Slot 3 = default ad query Y

   4. Slot 4 = default ad query Z

3. It generates a random number between 1 and 4, which is equal to the number of slots in the ad placeholder.

4. It matches the generated number with a slot in the placeholder. Because campaign ad query X occupies two of four slots, it has a 50% chance of being run. Default ad queries Y and Z each have a 25% chance of being run.

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

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:

1. It creates two slots in the ad placeholder and assigns ad query Y and ad query Z each to a single slot.

2. It generates a random number between 1 and 2.

3. It matches the generated number with a slot in the placeholder. Now, each ad query has a 50% chance of running.

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:

1. It determines the adWeight values for all documents that the query returns and adds them together.

   For example, an ad query returns the following three ads:

   • Ad X, with an adWeight value of 2

   • Ad Y, with an adWeight value of 1

   • Ad Z, with an adWeight value of 1

   The total weight for the documents that the query returns is 4.

2. It creates 4 slots, corresponding to the total weight in the query.

3. It places ad X, with a weight of 2 into 2 slots. Each of the other ads, with weights of 1, gets a single slot:

   1. Slot 1 = ad X

   2. Slot 2 = ad X

   3. Slot 3 = ad Y

   4. Slot 4 = ad Z

4. It generates a random number between 1 and 4, which is equal to the total weight in the query.

5. It matches the generated number with a slot. Because ad X occupies two of four slots, it has a 50% chance of being displayed. Ads Y and Z each have a 25% chance of being displayed.

 

---

Creating Ad Placeholder Tags

After a BA uses the E-Business Control Center to create ad placeholders, a BE 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

1. In a text editor, open a JSP.

2. Import the tag library by adding the following tag near the top of the JSP:

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

3. Find the location in which the Business Analyst wants to display the ad.

4. Use the following syntax to create the placeholder tag:

   <ph: placeholder= "{ placeholder-name | scriptlet }" >

   where placeholder-name refers to the name of an existing placeholder definition (see Figure 10-3) or where scriptlet returns the name of an existing placeholder. The name can be either the URI of the placeholder definition file (for example, "/placeholders/top-banner.pla") or just the placeholder filename without the .pla extension ("top-banner" in this example).

   Figure 10-3 Placeholder Names Must Match

   
    

Listing 10-1 shows an example from the heading include file of the wlcsApp reference application
(PORTAL_HOME\applications\wlcsApp\wlcs\commerce\includes\heading.inc).

All JSP files in the wlcs reference 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 10-1 Using a Scriptlet for the Placeholder Name

<% 

   String banner = (String)pageContext.getAttribute("bannerPh");
   banner = (banner == null) ? "/placeholders/cs_top_generic.pla" : banner;

%>

<!-- ------------------------------------------------------------- -->

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

  <tr>
     <td rowspan="2" width="147" height="108">
     <img src="<webflow:createResourceURL resource="/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 10-4 illustrates how WebLogic Portal renders the placeholder in the main.jsp file, which is the home page for the wlcs reference Web application.

Figure 10-4 Placeholder in the wlcs Web Application

 

For more information about the <ph:placeholder> tag, refer to Personalization Server JSP Tag Library Reference, in this guide.

 

---

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:

• XHTML (a fragment or an entire document). For this type of document, a placeholder passes the text directly to the JSP.

• 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 use to display the file. In your content management system, you can specify attributes for the <OBJECT> and <EMBED> tags.

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:

• Create and Compile a Java Class to Generate HTML

• Register the New Class

Create and Compile a Java Class to Generate HTML

To generate the HTML that the browser requires to display the MIME type, create and compile a Java class that implements the com.bea.p13n.ad.AdContentProvider interface. For information on this interface, refer to WebLogic Portal Javadoc.

After you compile the class, you must make sure the class is available to the application. One way to do this is to add the class appropriately to one of the deployed jar files, such as placeholder.jar or your own jar file. Another way to make the class available to the applicaticatoin is to save it under a directory that is specified in the system's CLASSPATH environment variable. For example, create a WL_PORTAL_HOME/classes directory and add it to the set-environmment script. For more information about the CLASSPATH environment variable, refer to "Setting Environment Variables," under "Starting and Shutting Down the Server" in the Deployment Guide.

Register the New Class

After you save the class in a directory that is in your classpath, you must notify WebLogic Portal of its existence:

1. Stop the WebLogic Portal instance that is running your application. For information on stopping a server, refer to "Starting and Shutting Down a Server" in the Deployment Guide.

2. Create a backup copy of PORTAL_HOME/application/your-application/META-INF/application-c onfig.xml

3. Open application-config.xml in a text editor and find the <AdService> element.

4. Add the following as a subelement of <AdService>:

   <AdContentProvider
   Name="MIME-type"
   Provider="name-of-your-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 pathname, 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 WL_PORTAL_HOME/classes to the system classpath, save your class to support AVI files as WL_PORTAL_HOME/classes/myclasses/MimeAvi.class.

   Alternately, if you had an already deployed JAR of your own EJBs called myServices.jar (which is listed in the application's META-INF/application.xml file), add myclasses/MimeAvi.class to that JAR file.

   To register your classname, add a subelement to the AdService element as illustrated in Listing 10-2.

   Listing 10-2 Add An AdContentProvider Element

   <AdService
         Name="wlcsApp"
         DisplayFlushSize="10"
         Rendering="com.bea.p13n.ad.AdContentProviderBase"
         EventTracker="com.bea.campaign.AdTracking"
         AdClickThruURI="AdClickThru"
         ShowDocURI="ShowDoc"
       >

         <AdContentProvider
           Name="text"
           Provider="com.bea.p13n.ad.render.TextContentProvider"
           Properties=""
         >
         </AdContentProvider>

         <AdContentProvider
           Name="image"
           Provider="com.bea.p13n.ad.render.ImageContentProvider"
           Properties="AdClickThruURI=AdClickThru;ShowDocURI=ShowDoc"
         >
         </AdContentProvider>

         <AdContentProvider
           Name="application/x-shockwave-flash"
           Provider="com.bea.p13n.ad.render.ShockwaveContentProvider"
           Properties="ShowDocURI=ShowDoc"
         >
         </AdContentProvider>

         <AdContentProvider
           Name="video/x-msvideo"
           Provider="myclasses.MimeAvi"
           Properties=""
         >
         </AdContentProvider>

     </AdService>

5. Save your modifications to application-config.xml.

6. Restart WebLogic Portal.

 

---

How Placeholders Select and Display Ads

Placeholders use the following process to select and display ads in a given JSP (see Figure 10-5):

1. Any of the following activities place ad queries in an ad placeholder:

   • You use the E-Business Control Center to define default queries for a placeholder.

   • As part of carrying out a campaign action, the Campaign Service adds queries to the placeholder.

2. When a user requests a JSP that contains a placeholder, if the ad placeholder contains more than one ad query, the Ad Service calls the Ad Conflict Resolver to select an ad query.

   For more information, refer to How the Ad Conflict Resolver Chooses a Query in this guide.

3. The Ad Service does the following:

   1. It forwards the query to the content management system. If the query returns more than one ad, the ad placeholder uses the adWeight attribute of each ad to determine which one to retrieve.

   2. If the ad is associated with an active campaign, it determines whether the campaign has fulfilled its goal of displaying the ad a specific number of times. If the ad has already been displayed the specified number of times, the Ad Service selects another ad.

   3. It sends data to the Events Service indicating that the placeholder has displayed the ad.

      For more information, refer to How an Ad Placeholder Chooses from Ad Query Results in this guide, and "Campaign Service Properties" under "The Server Configuration" in the Deployment Guide.

4. The ad placeholder renders the ad content and places it in the JSP at the location of the placeholder tag.

5. If a customer clicks on the ad, the Ad Service redirects the URL and notifies the Event Service that a customer clicked the ad.

   Figure 10-5 How Placeholders Display Ads

   
    
    

 

---

How to Configure Ad Placeholders in an Application

For the <ph:placeholder> and <ad:adTarget> tags to work correctly, you will need the following configuration:

• EJB references to ejb/PlaceholderService, ejb/AdBucketService, and ejb/DocumentManager must be specified in the Web Application's web.xml and weblogic.xml files.

• The com.bea.p13n.ad.servlets.AdClickThruServlet must be mapped to /AdClickThru/* in the Web Application's web.xml file.

• The com.bea.p13n.content.servlets.ShowDocServlet must be mapped to /ShowDoc/* in the Web Application's web.xml file.

For more information, see the Deployment Guide.
Also, refer to the web.xml and weblogic.xml files in WL_PORTAL_HOME/applications/portal/stockportal/WEB-INF.