Understanding Pagelet Development

Single Signon

Oracle delivers a component interface named PRTL_SS_CI that enables external applications to support a single signon solution with PeopleSoft portal applications. This enables users to sign in once when accessing the portal and not have additional sign-ins for each system that is referenced in your portal.

See Understanding Single Signon and Pagelets.

Layout

Observe the following rules for layouts:

• Avoid horizontal scrolling.

• Do not use page titles.

  The name of the content reference in the portal registry is used as the pagelet title.

• Pagelet instructions should not be necessary.

• Avoid group boxes whenever possible.

  Note: They may be necessary to separate sections.

• Left align text wherever possible.

• Deselect the Show Borders option for group boxes and scroll areas.

• Select View > Internet Options in PeopleSoft Application Designer to ensure that you can access all the styles available.

• Leave more than 20 percent spacing between field labels and field edit boxes because the rendered styles are larger in the browser than they appear in PeopleSoft Application Designer.

• Before bringing your pagelet into the portal, view it in PeopleSoft Application Designer. Select Layout > View in Browser.

Appearance and Character

The appearance of objects on pagelets, such as text, links, tables, and so forth, should be modified by means of the PeopleSoft style classes to retain a consistent appearance and character between your pagelet and the rest of the portal. PeopleSoft uses cascading style sheets (CSS). Style sheets are useful because they enable developers to change page attributes across multiple pages quickly and easily.

Each style sheet is composed of individual classes, which affect the formatting of each page. Classes control a broad range of characteristics, including font size, spacing, alignment, border width, weight, and color.

When creating the page, select the Use Default Style Sheet option. For any controls on the page, select the Use Default Style option.

All style sheets used in each pagelet on the page are referenced on the final page that is assembled by the portal. Therefore, a pagelet should not redefine any class that might be shared by other pagelets on the assembled page. If a class needs to be changed, define a new one.

The order of precedence for style sheets is:

1. Template.

2. Target component.

3. Pagelets – in the order that they are assigned.

Style sheet definitions are stored in the database. They are accessed and modified by means of PeopleSoft Application Designer. The default style sheet used by PeopleTools depends on your application release, but is either PSSTYLEDEF or PSSTYLEDEF_SWAN. The PeopleSoft Interaction Hub uses a PSSTYLEDEF or PSSTYLEDEF_SWAN derivative.

You can determine which style sheet is being used by selecting PeopleTools > Utilities > Administration > PeopleTools Options. The value in the Style Sheet Name field designates the style sheet used by the database.

Two ways are available by which you can see the style classes defined in a style sheet.

If you access PeopleSoft Application Designer, you can open the designated style sheet and view its definitions in a graphical interface.

Double-click any style class to view and modify its definition.

If you don't have access to PeopleSoft Application Designer and want to see the CSS file, you can access the file cached for the CSS on the web server. For example, on WebLogic you'll find the file in this directory:

....\peoplesoft\applications\PORTAL\site_name\cache

The file is generally named PSSTYLEDEF_1.css or PSSTYLEDEF_SWAN_1; however, it may have a slightly different name. For example, it might have a different numbered suffix.

Some of the most common styles used by pagelets include:

• PSTEXT

  General text label.

• PAADDITIONALINSTRUCTIONS

  Instructional text.

• PABOLDTEXT or PABOLDBLUETEXT

  Commonly used for group and category titles.

• PSPSMALLTEXT

  Commonly used for footers and branding (credits).

• PSPAGE

  Commonly used for background colors.

• PSLEVEL1GRIDODDROW

  Shaded row, which is typically light gray or light blue.

• PSLEVEL1GRIDEVENROW

  Lighter-colored row, which is typically white.

• PSCHECKBOX

• PSDROPDOWNLIST

• PSEDITBOX

• PSGROUPBOX

  Commonly used to create groupings or dividers.

• PSHYPERLINK

• PSPUSHBUTTON

• PSRADIOBUTTON

The following examples show ways in which these styles are used in HTML and translated into elements in the PeopleSoft Pure Internet Architecture interface:

This HTML generates the following interface:

<table border='0' cellpadding='0' cellspacing='0' cols='1' CLASS='PSGROUPBOX' style="border-style:none;" width='639'>		<tr>
			<td class='PSGROUPBOXLABEL' align='LEFT'>Language Settings</td>
		</tr>
			<td colspan='2'  valign='top' align='LEFT'>
				<label for='PSOPTIONS_LANGUAGE_CD' class='PSDROPDOWNLABEL'>Language Code:
				</label>
			</td>
			<td  valign='top' align='LEFT'>
				<span class='PSDROPDOWNLIST' >English</span>
			</td>
...
<input type='check box' name='PSOPTIONS_TRANS_CHG_LASTUPD' id='PSOPTIONS_TRANS_CHG_LASTUPD' tabindex='14' value="Y" />
	<label for='PSOPTIONS_TRANS_CHG_LASTUPD' class='PSCHECKBOX'>
			Translations Change Last Update
	</label>

This example illustrates the fields and controls in the Language Settings group box of the PeopleTools Options page.

This HTML generates the following interface:

<input type='text' name='STYLESHEET' id='STYLESHEET' tabindex='28' value="" class='PSEDITBOX' style="width:23px; text-align:RIGHT; " maxlength='2'/>
		<label for='PSOPTIONS_TEMPTBLINSTANCES' class='PSEDITBOXLABEL'>				Style Sheet Name:
		</label>

This example illustrates the Style Sheet Name field of the PeopleTools Options page.

Links and URLs

When processing page-based templates, the portal servlet uses a process called proxying to help ensure that users always stay within the context of the portal and that familiar portal features such as the universal navigation header do not disappear when a user clicks a link.

When a user signs in to a PeopleSoft portal, he or she signs in to a web server on which the portal servlet is running. The portal servlet processes all HTML that isn’t in the simple URL format, converting all URL references to point to the portal web server rather than the original URL. The original URL is still necessary to retrieve the requested content; it is stored in the new URL in the URL query string parameter. The portal servlet proxies all links and all form actions in this manner.

For example, assume that a user requests a page from an external website through a proxied link in the portal. The request arrives at the portal web server, invoking the portal servlet. The portal servlet then programmatically retrieves the page from the web server associated with the requested page. It proxies all the links on the retrieved response and sends the page (the contents of the HTTP response) back to the browser, formatted as the user would expect within the portal.

When a URL is invoked on a target page, as opposed to the homepage, the content associated with the URL is rendered within the target frame. The PeopleSoft Interaction Hub and header and left-hand area will remain. Therefore, proxying isn’t required to have the new content rendered in the context of the PeopleSoft Interaction Hub.

Performance

Homepages are cached on each user’s browser. The browser does not access the web server after the homepage is initially retrieved. You can enable or disable this feature, and also adjust the time interval before the web server is accessed again to get a fresh homepage. In any case, if a user clicks the browser Refresh button, the homepage is accessed from the web server again, overwriting the homepage cached on the browser.

The following PeopleCode function is used to trigger a refresh of the homepage:

FUNCLIB_PORTAL.TEMPLATE_FUNC.FieldFormula.ForceRefreshHomePage().

Additionally, the following configuration properties are associated with homepage caching. Any changes to these settings are applied to all users signing in to the web server.

• PortalCacheHomepageOnBrowser=<True or False>

  If set to True, the homepage is cached on the browser. If set to False, the homepage is not cached on the browser.

• PortalHomepageStaleInterval=<seconds until stale>

  A homepage cached on the browser is considered stale after the specified number of seconds. The next time a user accesses the homepage by clicking a link, the web server is accessed and the homepage is refreshed on the browser.

Because different browser versions do not process HTML in exactly the same way, the browserprops.xml file on the web server on which the portal servlet is installed enables you to disable homepage caching for selected browser versions.

This can be useful if you have one or two supported browsers and want to disable cache for nonstandard browsers that could pose an administration problem. Follow the instructions in the file to disable caching for certain browser types.

As with homepages, navigation pages are cached on each user’s browser. You can set options for navigation caching by using the Time page held in cache (METAXP) option.

Set the Time page held in cache option by navigating to My Personalizations and clicking the Personalize Option button for the General Options personalization category. Note that this option is set in minutes, not seconds. A change to this option is picked up by the application server immediately. However, because the users' browsers already have cache control set by the previous value of the option, you must delete the browser cache for the new Time page held in cache value to take effect.

Oracle enables you to prevent the system from caching PeopleSoft pages to the browser. You control browser caching using the EnableBrowserCache property in the configuration.properties file.

Being able to control browser caching is useful for situations in which PeopleSoft applications are deployed to kiosk workstations where multiple users access the applications. Enabling you to prevent caching means that users can't click the Back button to view another individual's transaction or view any other sensitive data.

The side effect of completely disabling caching is degraded performance. For each new page, the system must access the database. However, PeopleTools offers a compromise related to browser caching in the form of the Time page held in cache (METAXP) option discussed earlier.

You can enable browser caching for the navigation pages that remain relatively static. This option applies to PeopleSoft Pure Internet Architecture navigation pages, portal homepages, and navigation pages. Use it to take advantage of the performance gains of caching while limiting the amount of time that navigation pages—the menu pages—remain in cache.

The Time page held in cache option is set to 20 by default. To disable this option, enter 0 in the Override Value edit box. The minimum value in minutes for this option is 0 (disabled) and the maximum value is 525600, which is one year.

If the Time page held in cache option is set to 20, and if you assume that the time is 7 p.m. on August 24, then the header information in the HTML is dated like this:

Wed 24 Aug 2011 07:20:00 PM

This header information indicates that in 20 minutes the system needs to check for a new page. This reduces the performance degradation when no caching occurs at all.

By default, the EnableBrowserCache property is set to True.

If the EnableBrowserCache property is set to False:

• The system never caches pages. When a user clicks the browser Back button, she receives a Page Expired message in .

• The setting overrides any date and time header settings.

The following table helps illustrate the way in which the EnableBrowserCache option works with the METAXP option.

Multi-language Support

PeopleSoft applications currently support the following 33 languages:

• Arabic.

• Bahasa Malay.

• Bulgarian.

• Canadian French.

• Chinese (Simplified).

• Chinese (Traditional).

• Croatian.

• Czech.

• Danish.

• Dutch.

• English.

• Finnish.

• French.

• German.

• Greek.

• Hebrew.

• Hungarian.

• Italian.

• Japanese.

• Korean.

• Norwegian.

• Polish.

• Portuguese.

• Romanian.

• Russian.

• Serbian.

• Slovak.

• Slovenian.

• Spanish.

• Swedish.

• Thai.

• Turkish.

• UK English.

Pagelet Wizard can access the PeopleSoft runtime environment to determine details of a user’s profile, such as his or her language. For more information about how you can use this Pagelet Wizard feature to facilitate passing runtime parameters, such as language, see Pagelet Wizard documentation in this PeopleBook.

See Understanding Pagelet Wizard.

In addition, Java classes delivered with PeopleTools enable you to call PeopleCode from your Java program and access contextual information from the runtime system. If needed, language can be retrieved through a PeopleCode function that is accessible from Java. Further information about this feature can be found in this document.

See Developing Java-Based Pagelets.

Narrow Pagelets

With three-column layout, all pagelets are rendered as narrow pagelets. Narrow pagelets are designed to be approximately 300 pixels wide. Subtracting the border and the internal margin leaves 285 pixels for the content. A narrow pagelet appears in a column that is one-third the width of the portal homepage. Because the pagelet is narrow, you should provide a succinct list of values that users can quickly traverse. Select the minimum set of data that best encapsulate the pagelet content. A narrow pagelet typically accommodates a single 30-character field.

A pagelet that has been designed to fit in a narrow column can be rendered in a wide column as well. However, user interface issues can occur when a pagelet that has been designed to render in a wide column only is rendered in a narrow column. Therefore, a pagelet should always be able to operate in a narrow format.

This example shows the Discussion Forums pagelet as a narrow pagelet. The essential links and information are displayed in the narrow format.

Generally, all pagelets should be developed with the narrow column size as the default. However, a pagelet can be designed to take advantage of the additional space when it is rendered in a wide column.

Wide Pagelets

With two-column layout, the first column allows spacing for a narrow pagelet and the second column allows spacing for a wide pagelet. Wide pagelets are designed to span two-thirds of the width of the homepage. Subtracting the border and the internal margin leaves 650 pixels for the content. Although you can fit more data on the pagelet, the data must remain meaningful.

This example shows the Discussion Forums pagelet as a wid pagelet. In addition to the essential links and information that are also displayed in the narrow format, the wide format includes who posted a discussion topic or reply and when.

When the layout contains the wide column, the PORTALPARAM_COMPWIDTH query string parameter is set to wide and passed to the HTML denote the wide version. Developing a wide version of a pagelet is optional.

The PORTALPARAM_COMPWIDTH Parameter

The parameter PORTALPARAM_COMPWIDTH can contain the value Wide or Narrow and can be used to specify whether a pagelet is being rendered in a narrow or wide column. The function pgltAtion does not check or use this parameter, the narrow pagelet will just be rendered in a wider area.

This sample PeopleCode references the query string parameter PORTALPARAM_COMPWIDTH:

Component string &CompWidth;

&CompWidth = %Request.GetParameter("PORTALPARAM_COMPWIDTH");

If &CompWidth = "Wide" Then;
		TransferPage(Page.PT_CONTRK_PGLT_W);
End-If;

Banner Pagelets

Banner pagelets are the widest of all pagelets. Banner pagelets extend across the entire width of the homepage or dashboard page and span all columns regardless of layout. Both the two-column and three-column layouts enable you to add one banner pagelet that is positioned at the top of the page. Banner pagelets are designed to be 1240 pixels wide.

The portal uses the content reference attribute, PORTAL_BANNER_PGLT to appropriately position banner pagelets. You must manually enter this attribute name and its accompanying value.

This example shows the entry for the PORTAL_BANNER_PGLT content reference attribute:

See Creating Banner Pagelets.

Pagelet Extensions

Pagelet extensions are standard pages. They can be registered with a template that allows it to use the entire width of the browser with no side frame for navigation, or with a template that includes a side frame.

In the former case, no inherent sizing requirements are imposed. PeopleSoft pages are designed for browsers running with a resolution of at least 1280 x 1024. Therefore, when a side frame is not included, a pagelet extension should not be wider than 1190 pixels, accounting for borders and so forth.

In the latter case, a pagelet extension should not be wider than 375 pixels.

PeopleSoft Interaction Hub Guidelines

This section lists some HTML-related development guidelines for pagelets that you use in the PeopleSoft Interaction Hub.

• Within PeopleTools, attributes from all content are merged into the single <BODY> tag; be aware of the order of attribute precedence.

  The order of attribute precedence is:

  1. Template.

  2. Target content.

  3. Template components.

  Events beginning with on are naively combined, so if one of them issues a return, the following events will not run. All other attributes are not examined; rather they are used in order of precedence. For example, if both the template and a content component contain topmargin, the template attribute will be applied.

• Avoid large borders or anything that creates extraneous white space. Screen area on a homepage is valuable and data should be maximized.

• Avoid implementing anything that will make the pagelet width wider than the prescribed size. Making the user scroll horizontally is undesirable.

  Make your HTML vertically oriented. For instance, radio buttons should be placed vertically, not side-by-side. When you create a form, any buttons should appear under a text box, not next to it.

• Avoid using graphics that do not have thoughtful purpose. This is a business-oriented portal, so extravagant or extraneous images should not be used. If any are used, they should be purposeful and unobtrusive. No graphic should be wider than 218 pixels. A graphic larger than this size will force the width of the pagelet to exceed the size of a narrow pagelet.

• Avoid using any text or directives that force the pagelet to a width greater than 218 pixels.

• In general, avoid explicit sizing and allow the portal to set the width. Your text and graphics should then fit appropriately. For instance, placing text within an HTML table will allow it to wrap any long strings.

• When appropriate, use the PeopleSoft style sheet to ensure that the appearance and character of your pagelet is consistent with the rest of the PeopleSoft Interaction Hub content.

• When your pagelet does not use the entire width of the column, center the pagelet content.

• If a link takes the user to another website and you want it to display the content in a new window, rather than using target=_blank within the link tag, use:<a href="javascript:void window.open ('http://www.example.com/cgi-bin?article3');" class="PSHYPERLINK">