Working with Portal Templates

This chapter provides an overview of portal templates and discusses how to:

• Apply template types.

• Develop portal templates.

Understanding Portal Templates

The PeopleSoft portal integrates content from numerous sources and presents the merged content on a single web page in a coherent, consistent fashion that keeps users within the portal framework. A portal template tells the portal servlet what content to place on the assembled page and where each piece of content should be placed.

A portal template is HTML code. However, in addition to standard HTML tags, the portal template can include PeopleSoft tags that are used for giving instructions to the portal servlet during page assembly. A normal browser cannot interpret these special tags. The portal servlet follows instructions in the PeopleSoft tags and then removes them before passing the final page back to the user’s browser.

The content in a template falls into three categories:

• HTML for the template itself.

• HTML for the main target content.

• Additional HTML, such as for the navigation header.

Applying Template Types

This section discusses how to:

• Consider Template types.

• Use page-based static templates.

• Use frame-based static templates.

• Use frame-based dynamic templates.

Considering Template Types

Each portal template is either page-based or frame-based, and each template is either static or dynamic. There are four possible combinations of template types:

• Page-based static templates.

  These are content references with a usage type of HTML template and a storage type of Local (in HTML Catalog).

• Page-based dynamic templates.

  These are content references with a usage type of HTML template and a storage type of Remote by URL.

• Frame-based static templates.

  These are content references with a usage type of Frame template and a storage type of Local (in HTML Catalog).

• Frame-based dynamic templates.

  These are content references with a usage type of Frame template and a storage type of Remote by URL.

A page-based template uses HTML tables to generate a page. Content is placed in each table cell that is defined by the template. The portal servlet uses the page-assembly process to retrieve documents for each cell. The assembled page is then sent as a single unit to the user’s browser.

A frame-based template uses frames, rather than HTML tables, to divide the page into parts. The portal servlet constructs the appropriate URL for each frame (SRC tag in the frame set) and sends the entire frameset to the browser. The browser then retrieves the content for each frame.

A static template is based on HTML code that is entered into the HTML area of a template content reference (a content reference that exists in the Portal Objects\Templates folder of the portal registry). Bind variables cannot be used within the HTML area. The HTML includes any HTML that is required for the template itself, plus tags that specify the URLs for template pagelets. You can view and update the contents of a static template on the portal administration pages.

A dynamic template is retrieved from the web in real time, as part of the page-assembly process, rather than stored in the database with the content reference. A dynamic template can use bind variables. You cannot view the HTML contents of the dynamic template directly on the portal administration pages. Instead, the portal administration pages enable you to identify the URL that points to the resource that provides the template content. If the dynamic template is implemented by an iScript, you can use PeopleSoft Application Designer to navigate to the record and field where the iScript exists. The content provided by the URL is the HTML that is used for the dynamic template at runtime.

See Managing Portal Objects.

Using Page-Based Static Templates

This static template example combines a universal navigation header with target content. It is based on HTML tables, not frames. This template is composed of HTML for three items:

• The template itself.

  Some HTML is required for the overall template. The code for this template is represented in the following example by all the non-emphasized text. This HTML code remains on the assembled page that is sent to the user’s browser after the page-assembly process.

• A template tag for the universal navigation header pagelet.

  This is the first block of HTML code that is emphasized in the following example. At runtime, the portal servlet replaces the IClientComponent Source tag with the navigation header in the template for the final assembled page.

• A template tag for target content.

  At runtime, the portal servlet replaces the Target tag—the second block of emphasized HTML code in the following example—with whatever content the user requested by clicking a link or button.

<html>
<head>
</head>
<body>
<table>
<tr><td>
<Pagelet Name="UniversalNavigation">
    <SOURCE Node="LOCAL_NODE" href="s/WEBLIB_PORTAL.PORTAL_HEADER.FieldFormula.
			IScript_UniHeader" />
</Pagelet>
</td></tr>
<tr><td>
<Target Name="TargetContent"/>
</td></tr>
</table>
</body>
</html>

Using Frame-Based Static Templates

This example is that of a static template based on frames. The pictured Content Ref Administration page shows how the HTML exists within the context of the whole content reference. Note that the usage type is set to Frame template. In the previous example of a page-based template, which uses HTML tables, the usage type would have been set to HTML template.

Using Frame-Based Dynamic Templates

All dynamic portal templates are retrieved from a URL rather than from an HTML document. Most commonly, the URL for dynamic templates is an iScript URL. As with static templates, the template content reference must be defined as a template on the portal administration pages. However, instead of including specific HTML content, the dynamic template references an iScript. The iScript is associated with a specified field in a specified record.

This example shows a frame-based dynamic template named DEFAULT_TEMPLATE in the Portal Objects folder:

The content reference storage type is set to Remote by URL. This setting is required for dynamic templates. Additionally, no HTML area displays the associated HTML code for the template, as you would expect with a static template. Instead, as the URL type for this example is set to PeopleSoft Script, an iScript parameters area appears on the page, in which you can define the record name, field name, PeopleCode event name, and PeopleCode function name that specify the iScript to use for the template.

The iScript that dynamically generates the template is located in the WEBLIB_PORTAL record in the PORTAL_NAV field, as shown in this example. Additionally, the iScript function is associated with the FieldFormula PeopleCode event. The PeopleCode function name is IScript_Portal_Trans_Dyn.

To view the iScript on which this dynamic template is based, open the record (WEBLIB_PORTAL) in PeopleSoft Application Designer and select the appropriate field (PORTAL_NAV), as shown in this example:

Once you open the appropriate record and field (PORTAL_NAV) in PeopleSoft Application Designer, you can view the FieldFormula PeopleCode. The iScript is referenced by the PeopleCode function name in the template’s definition. An easy way to find the exact reference is to copy the PeopleCode function name from the template definition and paste it into the Find dialog box of the PeopleCode editor once you open the corresponding record and field.

You now can see the code of the iScript that is referenced by the portal template, as shown in this example:

The following code calls an HTML object called PORTAL_TRANSACTION_DYN from the HTML catalog and passes the object a bind variable. The resulting HTML code forms the basis for the dynamic portal template at runtime.

&HTML = GetHTMLText(HTML.PORTAL_TRANSACTION_DYN);
 &Response.Write(&HTML));

You can open the HTML object PORTAL_TRANSACTION_DYN in PeopleSoft Application Designer, as shown in this example, and see where the bind variable is passed in. This is a frame-based template, as Frame tags are present.

See Also

Administering Content References

Developing Portal Templates

This section discusses:

• Template pagelets based on pages.

• Inheritance of style classes.

• Template pagelet tags.

• Considerations for non-PeopleSoft content providers.

• Considerations for frame-based templates.

• Partial path nodes.

• Pagelet names in templates.

• Considerations for forms and templates.

• Error message display.

Template Pagelets Based on Pages

Template pagelets can be provided by any URL, but usually they are based on either a page or an iScript. If you are using template pagelets based on pages, add the query string parameter &target= PanelGroupName at the end of the query string parameter list for the template pagelet in the template HTML. This prevents PeopleSoft Pure Internet Architecture from assuming the same default name, Main, for each page. Failure to specify the target parameter results in a JavaScript error when the portal servlet tries to load the template. If there is more than one form with the name Main on the same page, the JavaScript on that page cannot determine which Main component to use. In the template HTML, add the target parameter to the source specification of each page-based template pagelet that is not meant to be the target content.

Here is an example:

<tr> 
<td><Pagelet Name="Related Links">
     <Source Node="LOCAL_NODE" href="c/PORTAL_ADMIN.PORTAL_RLNK_1COL.GBL?target=relatedlinks"/></Pagelet>
</td>
</tr>

Inheritance of Style Classes

When the portal servlet assembles portal pages based on PeopleSoft Application Designer pages, the assembled pages inherit the style classes that are defined for them in PeopleSoft Application Designer. Because you can develop a template that includes pagelets built with different style sheets in PeopleSoft Application Designer, you can have conflicting style classes in your template.

For example, if you have a style class named Big on page X and you also have a style class named Big on page Y, there may be conflicting styles on the resulting page. When conflicting style classes exist, the style sheet that is associated with the page that is used for the target content always takes precedence over competing style sheets in the template.

Template Pagelet Tags

Template HTML can contain three PeopleSoft-specific tags that are used as portal servlet directives to assemble content on the page: Pagelet tags, Source tags, and Target tags.

Pagelet

Note the following attribute, element, and content information for the Pagelet tag:

Source

Note the following attribute, element, and content information for the Source tag:

Contents must be escaped. Ampersands must be written as &. Use the IClientComponent tag to specify content that is not specific to the PeopleSoft Pure Internet Architecture. If a pagelet is implemented by a web server that is not a registered content provider, the entire URL of the pagelet can be specified in the Source tag contents, and the product attributes can be omitted.

Target

Note the following attribute, element, and content information for the Target tag.

Considerations for Non-PeopleSoft Content Providers

To determine which template to apply to requested content, the portal servlet invokes the portal registry API to look up the content reference that is associated with the target content URL.

Warning! The information in this section applies to any content that is generated by a system where the PeopleTools release is earlier than 8.4, or any time the portal cannot determine from the submitted URL what content reference is being requested.

The same URL can supply different content pages depending on the context. For example, with PeopleSoft application pages, the URL for submit buttons before PeopleTools 8.4 always looks like this: http://server/servlets/iclientservlet/peoplesoft8.

Because of this, the target content can specify its registered URL by using a custom response header, PortalRegisteredURL. When the target content supplies this response header, the portal servlet uses it to identify the URL that is registered in the portal, rather than using the actual URL that is used to get the content. All PeopleSoft Pure Internet Architecture technologies, such as pages, iScripts, and queries, supply this URL.

The value of this header must be the string with which the page should be registered. You must register the content with the identical string that it will return as this header.

If content does not return the header information, the portal servlet identifies the content by the URL in the request that is submitted to the portal.

You can override the value of the PortalRegisteredURL response header in a PeopleSoft Pure Internet Architecture script or page by adding the header to the response yourself, like this:

%Response.SetHeader("PortalRegisteredURL", &myURL);

You can do this to register the content with additional parameters.

Considerations for Frame-Based Templates

In a frame-based template, all relative URL references refer back to the psc servlet. To construct a URL reference to a page that is assembled by the portal servlet, use either the GenerateXXXXPortalURL or GenerateXXXXPortalRelURL PeopleCode functions.

Partial Path Nodes

URLs that are not registered but partially match a registered node have the template of the associated node applied. This helps you to manage unregistered URLs and to ensure that they achieve a consistent appearance within the portal. Most pages have the template formatting that you and portal users expect, rather than resorting to the default template when an exact node cannot be found.

This table shows several examples of nodes, the URI, and some sample URLs that would use the template that is specified by the node:

Pagelet Names in Templates

You can specify a pagelet name in the template rather than specifying a URL. This is the syntax:

<Pagelet Name="My Pagelet">
<Source Product="Portal"  Pagelet="MY_PAGELET" />
</Pagelet>

If the portal servlet sees the Pagelet attribute in the Source tag, it looks up that pagelet name in the registry and uses the associated URL there.

Considerations for Forms and Templates

When posting data from a form in an HTML template, post data is lost if the action of the form is in a frame template. To solve this problem, make the frame source for the target a special request to the portal to repost the form data. The HTML response to that request includes a form containing the posted field and value pairs in hidden input fields and a Script tag that submits that form. When the browser receives this request, the JavaScript immediately submits the form to the original URL, causing the original post request to occur.

To make the frame source for the target a special portal request:

1. Construct the frameset.

   The source of the target frame is the portal, with the query string cmd=framerepost&key=xxx (or something similar).

2. Store the post data on the session object as a PropertySet (name and value pairs) for later retrieval, with a key.

   The key must uniquely identify the post data. The URL to post to can be kept in the PropertySet or put on the query string.

3. When the portal receives a frame repost request, it uses the incoming key to look up the stored PropertySet, then uses PropertySet to construct the HTML response with the name and value pairs in hidden input fields.

   The form also has a Submit button. The HTML response contains an inline JavaScript (after the form) that submits the form.

See the PeopleTools 8.45 installation guide for your database platform

Combining Forms and Frames

If you include a form on a page that’s been assembled by the portal servlet, and that page’s target is displayed in a frame (either in a frame template or in a nontemplate frame), then the form action cannot be Post. The portal servlet retrieves the page by using Get—not Post—regardless of the form action. Therefore, form data is lost if the form action was originally Post. Making the form action Get resolves this problem.

Error Message Display

When a pagelet cannot be retrieved, an error message appears.

You can disable this error message. If the error is not displayed, then the pagelet disappears from the template without a message to the user.

To control the display of this error message, use the DisplayError attribute of the IClientComponent tag:

<IClientComponent Name="Example" DisplayError=false>
   <Source Product="">http://www.InvalidServer/InvalidPage.html</Source>
</IClientComponent>

If the portal servlet finds DisplayError equal to False, it does not display the error but adds the empty pagelet comment tags. If DisplayError is equal to True, or if the attribute is not found, the error message is displayed.

This feature works best when the HTML for the template can flow around the empty content properly.