PeopleTools 8.52: PeopleTools Portal Technologies

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 four categories:

HTML for the template itself.
HTML for the main target content.
HTML for the related target content.
Additional HTML, such as for the navigation header.

Applying Template Types

This section provides an overview of template types and discusses how to:

Use page-based static templates.
Use frame-based static templates.
Use frame-based dynamic templates.
Use iframe-based dynamic templates.

Understanding Template Types

Each portal template is either page-based, frame-based, or iframe-based, and each template is either static or dynamic. Template types come in five possible combinations:

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.
iFrame-based dynamic templates.

These are content references with a usage type of iFrame 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 frameset) and sends the entire frameset to the browser. The browser then retrieves the content for each frame.

An iframe-based template uses HTML with embedded inline frames to divide the page into parts. The portal servlet constructs the appropriate URL for each section of the page and sends the HTML to the browser. The browser then retrieves the content for each section and each inline 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.

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

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 preceding example by all the nonemphasized 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 preceding example. At runtime, the portal servlet replaces the Pagelet 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 previous example—with whatever content the user requested by clicking a link or button.

Using Frame-Based Static Templates

This is an example of a static template based on frames:

The 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 frame-based 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 PT_85X_FRAMES_TEMPLATE in the Portal Objects, Templates 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, when 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_PT_NAV record in the ISCRIPT1 field, as shown in this example:

Additionally, the iScript function is associated with the FieldFormula PeopleCode event. The PeopleCode function name is IScript_PT_Frames_Template.

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

Once you open the appropriate record and field 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 PT_DEFAULT_FRAME_TEMPLATE from the HTML catalog and passes the object bind variables:

%Response.Write(GetHTMLText(HTML.PT_DEFAULT_FRAME_TEMPLATE, &frameRows, &encrypted⇒ UserId, &params3, &headerFrameTitle, &navFrameTitle, &contentFrameTitle, &relatedContentFrameTitle, &charSet, &pt⇒ CommonJS, &ptUtilJS, &ptEventJS, &ptRCMenuJS, &ptRCServiceJS, &ptRCJS, &saveWarnJS));

The resulting HTML code forms the basis for the dynamic portal template at runtime. You can open the HTML object PT_DEFAULT_FRAME_TEMPLATE in PeopleSoft Application Designer, as shown in this example, and see where the bind variable is passed in (note that this is a frame-based template, as Frame tags are present):

Using iFrame-Based Dynamic Templates

All dynamic iframe-based 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 other 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.

Important! HTML templates are deprecated as of PeopleTools 8.50. PeopleSoft applications require iframe templates to function as designed. Features that are unsupported in HTML templates experience significant or total loss of functionality; such features include:

• Modal windows used for prompts, secondary pages, and grid zoom.

• Main Menu drop-down navigation.

• Related content.

• WorkCenter pages.

• Global search header.

This example shows an iframe-based dynamic template named DEFAULT_TEMPLATE in the Portal Objects, Templates folder:

The iScript that dynamically generates the template is located in the WEBLIB_PT_NAV record in the ISCRIPT1 field, as shown in this example:

Additionally, the iScript function is associated with the FieldFormula PeopleCode event. The PeopleCode function name is IScript_PT_Frames_Template.

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

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 the PT_IFRAME_TEMPLATE HTML object from the HTML catalog and passes the object bind variables:

Return GetHTMLText(HTML.PT_IFRAME_TEMPLATE, &charSet, &requiredToolsSS, &sys⇒ DefaultSS, &domainJS, &expireJS, &ptCommonJS, &ptEventJS, &ptUtilJS, &ptAjaxJS,⇒ &crossDomainJS, &saveWarnJS, &iframeHdrJS, &iframeJS, &rcJS, &navHeader.HTML,⇒ &nav2JS, &ptPopupJS, &params1, &encryptedUserId, &rcMenuJS, &rcHTML1, &tgtIframe⇒ Title, &rcServiceJS, &cssOverride);

The resulting HTML code forms the basis for the dynamic portal template at runtime. You can open the PT_IFRAME_TEMPLATE HTML object in PeopleSoft Application Designer, as shown in this example, and see where the bind variable is passed in (note that this is an iframe-based template, as <iframe> tags are present):

Inline frame-based, or iframe-based, templates enable you to embed a frame within an HTML document rather than as a frameset. You can use the iframe <source> attribute to load content into the template. PeopleSoft applications use this attribute for target content only. The header and navigation content are in the HTML document itself as you see in the preceding PT_IFRAME_TEMPLATE HTML definition:

Note the following points about the standard iframe template:

The Usage Type is set to Inline frame template; this is a requirement for all iframe-based templates.
The iframe HTML definition supports only the <pagelet> and <target> meta-tags.

Important! The IClientComponent meta-tag is not supported.
Using inline frames enables you to click the navigation and see only the target content change. The entire page does not refresh. This approach allows for much more flexibility and facilitates the header and navigation working together.
When you navigate to different content within the iframe template, the URL in the browser address bar may not be up to date.
If you create your own iframe-based template, include the !DOCTYPE at the top of the code.

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 more than one form exists 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 may 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, conflicting styles may be 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:

Attributes	Name. Used to identify the component in a comment in the final assembled page.
Elements	Source tag.
Contents	None.

Source

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

Attributes	Product tag. Used to identify which PeopleSoft Pure Internet Architecture web server to route to. The Product tag value should be the name of the registered content provider for the content.
Elements	None.
Contents	Query string to access the page or iScript implementing the component.

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.

Attributes	Name. Used to identify the component in a comment on the final assembled page.
Elements	None.
Contents	None.

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

Note. When the content reference isn't registered, it doesn't use the template defined for the node. Instead, it uses the default template. Therefore, unregistered URLs use the default template, not the template assigned to the node.

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

Node	URI	Sample Match
Yahoo	http://www.yahoo.com	http://www.yahoo.com/business/webleaders/peoplesoft.html
Yahoo Sports	http://www.yahoo.com/sports	http://www.yahoo.com/sports/nba/heat/teamreport.html
Yahoo NFL	http://www.yahoo.com/sports/nfl	http://www.yahoo.com/sports/nfl/dolphins/teamreport.html

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 the application posts 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:

Construct the frameset.

The source of the target frame is the portal, with the query string cmd=framerepost&key=xxx (or something similar).
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.
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.52 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.