Understanding Pagelet Development
This section discusses:
Pagelet development guidelines.
Pagelet development considerations.
Pagelet development options.
HTML design considerations.
Follow these guidelines when developing new pagelets:
Adhere to object naming standards.
Do not provide any filter, sort, or refresh buttons because they also require trips to the application server.
If you enable the cache homepage option in the web profile, the pagelet must be display-only and cannot be interactive.
Because the portal servlet performs page assembly and proxying only on blocks of HTML, a pagelet must:
The portal servlet will issue an HTTP request to the registered URL.
Be HTML 4.0 compliant.
The HTML returned will be combined with HTML from other pagelets to form the entire web page.
Be sized appropriately.
The pagelet's width should conform to the narrow or wide guidelines discussed in the Sizing section in this document.
Pages created by way of PeopleSoft Pure Internet Architecture conform to these requirements. However, these requirements are not exclusive to PeopleSoft. As mentioned, pagelets can also be from remote, non-PeopleSoft systems, such as static HTML files or dynamically generated HTML from a variety of technologies such as JavaServer Pages (JSPs), Java Servlets, Microsoft Active Server Pages (ASPs), Perl scripts, and CGI programs.
When developing pagelets, you should also consider the following topics.
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.
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.
Selectin 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
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:
Pagelets – in the order that they are assigned.
Note: In the same way that PeopleTools supports subrecords to enable shared definitions between records, you can define substyle sheets to share a common set of classes. A substyle sheet has all of the properties of a style sheet.
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 Style Sheet Name field designates the style sheet used by the database.The value in the
Two ways are available by which you can see the style classes defined in a style sheet.
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:
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:
General text label.
PABOLDTEXT or PABOLDBLUETEXT
Commonly used for group and category titles.
Commonly used for footers and branding (credits).
Commonly used for background colors.
Shaded row, which is typically light gray or light blue.
Lighter-colored row, which is typically white.
Commonly used to create groupings or dividers.
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 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>
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.
Note: If URLs are included in your HTML, you must use absolute URLs as opposed to relative URLS.
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.
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.
Important! If any homepage pagelet in your implementation uses interactive mode, you must disable browser homepage caching in the web profile.
The following PeopleCode function is used to trigger a refresh of the homepage:
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 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.
No caching due to the 0 value in METAXP.
Pages are cached with expiration values set in Greenwich Mean Time (GMT) based on the Time page held in cache value (METAXP).
No caching. The EnableBrowserCache option setting overrides the Time page held in cache value (METAXP).
PeopleSoft applications currently support the following 33 languages:
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.
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.
You can create a pagelet using several ways. Ultimately, the portal servlet assembles HTML, so the key is determining how to generate the HTML. Some methods leverage PeopleTools, while other options allow pagelet creation without PeopleTools.
One set of options is to develop pagelets with PeopleTools. This is the most straightforward approach if you are dealing solely with data from PeopleSoft applications. The two types of PeopleTools-based pagelets are:
PeopleTools dynamically generates the appropriate HTML to render the page data based on the definitions created within PeopleSoft Application Designer. This is the most straightforward approach when the data being rendered is in a PeopleSoft application database.
You can write a PeopleCode function that renders HTML using %Request and %Response objects, which are similar to ASP or JSP programs. This allows more control over data retrieved and enables you to conditionally render HTML. This approach gives you maximum flexibility, but unlike the PeopleSoft Pure Internet Architecture page approach, you must code for things such as multilanguage and browser support.
The focus of this document is a set of options that can be used to create a pagelet application with one of the many technologies that generate HTML. This may be the approach you take if you’re integrating a non-PeopleSoft system with the PeopleSoft Interaction Hub. For example, you’re applying business logic to data from a non-PeopleSoft system, or you might be combining data from a PeopleSoft application with other systems.
The pagelet can be written in a variety of technologies, including:
Internet server API (ISAPI).
Tool Command Language (Tcl).
You can convert your own HTML into a pagelet in several ways:
Pagelet Wizard walks you through a series of steps involved in creating and publishing a pagelet. Portal administrators and nontechnical users can integrate and transform data from a wide variety of data sources, both internal and external to PeopleSoft applications.
External sources include web applications that can be referenced with a URL, HTML block (such as a form or table), and Java classes. You do not need to have PeopleSoft-specific application development tools or skills to be able to create pagelets.
You can also choose to register a URL, such as a JSP or ASP, directly in the portal registry.
The homepage layout can vary based on end-user personalization. These two layout choices are available for homepages and dashboard pages:
The three-column layout divides the homepage into three equally-sized columns. In PeopleSoft applications, these are called narrow columns.
The two-column layout divides the homepage into two differently-sized columns: one narrow column and one wide column, which is twice the width of the narrow column.
Because pagelets must function in two possible homepage layouts, it is column size that drives pagelet size. This fact is evident in the three categories of pagelet widths that are listed here:
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.
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.
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.
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
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 pgltAtiondoes 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
Component string &CompWidth; &CompWidth = %Request.GetParameter("PORTALPARAM_COMPWIDTH"); If &CompWidth = "Wide" Then; TransferPage(Page.PT_CONTRK_PGLT_W); End-If;
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.
Note: The actual number of pixels that are available for content varies based on the resolution of your display and the rendering engine of your browser.
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.
Important! Homepages and dashboard pages can display one banner pagelet only. If more than one pagelet on a homepage includes the PORTAL_BANNER_PGLT attribute, the system recognizes the attribute for the first pagelet and ignores the attribute for any other pagelets.
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.
Consider these HTML-related guidelines when you are designing pagelets:
Ensure that the pagelet encapsulates data to provide at-a-glance summary information.
Ensure that the pagelet provides links to detailed application pages.
Avoid large borders or a design that creates extraneous white space. Screen area on a homepage is valuable and data should be maximized.
Avoid designs that make the pagelet wider than the prescribed size. This undesirable design forces the user to scroll horizontally, so you should design your HTML to be vertically oriented. For instance, radio buttons should be arranged vertically, not side-by-side. When you create a form, buttons should appear below a text box, not next to it.
Because this is a business-oriented portal, avoid extravagant or extraneous graphics. If you use graphics, they should be purposeful and unobtrusive. No graphic should be wider than 218 pixels, which would force the pagelet to be wider than a narrow pagelet.
Avoid using any text or HTML tags that force the pagelet to a width that is greater than 218 pixels.
In general, avoid explicit sizing. Let the browser render content in the space that is available, which should allow your text and graphics to fit appropriately. For example, place text in an HTML table to enable the table 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 PeopleTools portal content.
When your pagelet does not use the entire width of the column, center the pagelet content.
If a link on the pagelet takes the user to another website and you want to display the content in a new window, rather than using target=_blank in the link tag, use the following code:
If a pagelet has personalization options, the pagelet should have a default mode. In default mode, ensure that the pagelet includes a standard set of data and a message conveying that default data can be personalized.
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:
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:
As mentioned earlier, this is a business-oriented portal. Although content and name recognition are important, they are secondary to the primary goal of enabling end users to perform their work in a more efficient manner. Thus, any branding should be subtle and never detract from the pagelet content or the rest of the portal.
Thus, for a user to operate within the PeopleSoft Interaction Hub product, a pagelet developed outside of PeopleSoft can credit the source developer, but must follow these standards:
Branding on a homepage pagelet should be done by means of text only and should be placed at the bottom of the pagelet. No organization logos can be placed on the pagelet without permission from Oracle. You can use “Provided by XXX,” where XXX is the name of your company. Also, XXX can be a link to an appropriate web page.
Organization logos and further information about your organization, products, and services should be located on the pagelet personalization page or other pagelet extensions.
Generally, graphics for organization logos should not be larger than 100 pixels wide x 40 pixels high.
The HTML used is shown here:
<table border=0 cellspacing=1 cellpadding=0> <tr> <td><!-- start of search form --> <form method="POST" action="http://www.example.com/cgi-bin/dofind.cgi"> <center> <font class="PSEDITBOXLABEL">Enter keyword:</font> <input name="word" value=""> <br> <input type="submit" value="Search"></center> </form> <!-- end of search form --></td> </tr> <tr> <td><!-- start of optional directions --> <font class="PAADDITIONALINSTRUCTIONS">General directions can be provided here. Remember that pagelets should be as easy and intuitive to use as possible.<br> <br> </font> <!-- end of optional directions --></td> </tr> <tr> <td><!-- start of footer for branding --> <center> <font class="PSPSMALLTEXT">Provided by <a href="http://www.example.com/">Content Source Company</a> </font> </center> <!-- end of footer for branding --></td> </tr> </table>
Note how this sample pagelet adheres to the standards mentioned previously:
It uses a table to help wrap words, rather than allowing long strings to dictate the width of the pagelet.
All text uses the PeopleSoft styles, such as PSEDITBOXLABEL, PAADDITIONALINSTRUCTIONS, and PSPSMALLTEXT.
The branding is small and no graphics are used, thus adhering to the branding standards mentioned previously.