Developing Portal Templates

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>

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

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.

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.

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.

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 examples of nodes, the URI, and sample URLs that would use the template that is specified by the node:

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.

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:

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 PeopleSoft 9.2 Application Installation for your database platform.

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.