Designing Template Pagelets For Intelligent Context Manager

Appendix: Designing Template Pagelets For Intelligent Context Manager

This appendix discusses how to:

Design template pagelets.
Expose a custom key structure to the Intelligent Context Manager(TM).
Use the Intelligent Context Manager API.

Note. Template pagelets can also be created using Pagelet Wizard. We recommend that you consider using this as it provides a means for simple and convenient creation and maintenance of template pagelets.

This chapter is meant to provide information about how to create template pagelets that are more complex than those that can be created using Pagelet Wizard.

Designing Template Pagelets

Unlike homepage pagelets, template pagelets are usually designed to work with context relationships. That is, template pagelets are usually required to retrieve the current target page context and display relevant information accordingly.

For examples of context aware processing, examine the template pagelets and associated features delivered with your application

Template pagelets can be created based on either PeopleSoft Pure Internet Architecture pages or iScripts.

Note. Whether template pagelets are created using PeopleSoft Pure Internet Architecture pages or an iScript, they will also require some PeopleCode development to retrieve information about the target page to enable context sensitivity.

Sample iScript Template Pagelet

The following code is for example purposes only and should not be considered as a design template.

import EPPLN_TEMPLATE_PAGELET:*;
/***********************************************************************
*/
/* Generic Template Pagelet iScript Sample
*/
/* Sample code to demonstrate how to use the EPPLN_TEMPLATE_PAGELET
*/
/* app package classes to generate a template pagelet in iScript.
*/
/**********************************************************************
*/
Function iScript_TemplatePagelet (&Type As String)
		&TPRequest = create TPRequest();
		&TPResponse = create TPResponse();
		If &TPResponse.isThisPageletMinimized() Then
			&HTML = "";		/* pagelet is minimized - only needed for invisible
										pagelets */
		Else
			If &TPRequest.isTCKeyDependant() Then
				If &TPRequest.isTCAvailable() And
						&TPRequest.GetNumTCKeys() > 0 Then
					For &i = 1 To &TPRequest.GetNumKeys()
						&KeyName = &TPRequest.GetTCKey(&i);
						&KeyValue = &TPRequest.GetTCKeyValueByIndex(&i);
						If All(&KeyValue) Then
/* Process key/value pair */
&HTML=result of processing
							End-If;
						End-For;
					Else
						/* Processing for key dependant - but keys not available */
						&HTML=result of processing
					End-if;
				Else
					/* Processing for non-key dependancy */
					&HTML=result of processing
				End-if;
		End-if;
		&TPResponse.WritePageletHTML(&HTML, "", "");
End-Function;

Defining Hidden Template Pagelets

iScript-based template pagelets can be defined so that they can be hidden. When a template pagelet is hidden, no information about that pagelet will be displayed to the user, including the template boundary box and pagelet title. This is useful when you only want to display information when a specific context is detected.

To create a hidden template pagelet, you will need to write a special pagelet output so that the pagelet container will only be generated when appropriate.

Instead of using the %Response.Write method to write HTML directly, make a buffer variable available to display the HTML code. To create the pagelet output, a call to the method TResponse.WritePageletHTML (&HTML, "", "") should be included.

Note. PeopleSoft recommends calling the WritePageletHTML method with a blank HTML buffer variable. When using this method, no container is created and no trace of the pagelet is visible to the end user.

When the template pagelet is registered, the attribute CANBEHIDDEN must be set with the value of TRUE.

Exposing a Custom Key Structure to the Intelligent Context Manager

To expose a custom key structure to the Intelligent Context Manager, one of the following two custom JavaScript objects must be created on the target application page:

PIA_KEYSTRUCT.

Primary key structure object. This object is automatically created with no page modifications necessary.
PS_KEYSTRUCT.

Secondary key structure object. This object is primarily used to avoid potential corruption due to the autogeneration of a PIA_KEYSTRUCT object by the toolset.

Note. Both the PIA_KEYSTRUCT and the PS_KEYSTRUCT objects can be present on the same page. However, if both objects contain a value for the same key, the value set in PIA_KEYSTRUCT will take precedence.

The following is an example of exposing the following two non-search parameters as key values for the Intelligent Context Manager: akey1:avalue1 and akey2:avalue2.

Using PeopleSoft Application Designer, add an HTML area to the page and link it to the DEMOFIELD field on the workrecord WORKREC. In the appropriate PeopleCode events, add the following:

WORKREC.DEMOFIELD.Value = "<SCRIPT Language='JavaScript'> var PS_KEYSTRUCT = 
{akey1: 'avalue1 ',akey2: 'value2 '};</SCRIPT> ";

Note. The example assumes that the target application and PeopleSoft Enterprise Portal have been set up on the same internet domain and are configured. Specifically, it is a requirement that both have an internet address similar to http://xxx.company.com/... and that the PeopleSoft Enterprise Portal has its domain set to company.com.

Using the Intelligent Context Manager API

This section lists the application package EPPLN_TEMPLATE_PAGELET delivered with the PeopleSoft Enterprise Portal. The classes, methods, and properties in this package are used to provide a supporting structure for template pagelets.

TPRequest Class

The following are the TPRequest class methods.

GetTCKeys

Description

Returns the key field names available from the target content page that have been defined through the Intelligent Context Manager for this target content page. Returns Null if the list of key field names is not available.

GetTCKeyValue(&Key As string) Returns string

Description

Returns the value of a key field from the target content page. Always returns as a string regardless of the actual field data type as defined on the page. Returns Null if the specified key value is not available.

GetNumTCKeys() Returns number

Description

Returns the number of key fields available from the target content page. Returns Null if key fields are not available.

GetTCKey(&KeyNum As number)

Description

Returns the name of a key field from the target content page, accessed by index number. The index number is in the same order as the order of the array returned by GetTCKeys(). Returns null if key field names are not available.

GetTCKeyValueByIndex(&Key As number)

Description

Returns the value of a key field from the target content page, accessed by index number. This index number is in the same order as the index of GetTCKey() and GetTCKeys(). Returns Null if the specified key value is not available.

isPageletTCKeyDependant

Description

Returns true if the current pagelet instance was defined to be dependant on target content key values. Otherwise returns false.

isTCKeyAvailable()

Description

Returns true if key values from the target content page are available. Otherwise returns false.

property string PortalContentURL

Description

Returns the URL of the target page as an exact match to that stored in the portal registry. Returns Null if the target page is not registered in the portal registry.

property string PortalActualURL

Description

Returns the value of the PortalActualURL query string parameter, which corresponds to the actual URL of the target page. Provided as a convenience method.

property string CREF_Name

Description

Returns the CREF Name field from the portal registry for the current template pagelet.

property string CREF_Label

Description

Returns the CREF Label field from the portal registry for the current template pagelet.

property ApiObject TargetContentCREF

Description

Returns a Portal Registry CREF object pointing to the CREF for the TargetContent page. Used to uniquely identify target pages.

property string TargetFullURL

Description

Returns the full URL of the target page, including any additional key parameters needed to uniquely identify the target page.

TPResponse Class

The following are the TPResponse methods:

WritePageletHTML(&HTML As string, &LABEL As string, &OBJNAME As string)

Description

Used by template pagelets that can be invisible and also have the CANBEINVISIBLE CREF attribute set. If the pagelet is not to be displayed, this function should be called with no value for &HTML.

&LABEL is the label text that will be shown on the box displayed to the user. Leaving this label clear will cause the Intelligent Context Manager to look up the appropriate value, usually the CREF name of the template pagelet. PeopleSoft recommends that &LABEL and &OBJNAME be clear.

Note. This method should not be used for template pagelets without the CANBEINVISIBLE attribute set.

isThisPageletMinimized

Description

Used by template pagelets that can be invisible to determine whether the current instance represents a call when the pagelet is minimized. When minimized, no data will be shown within the pagelet. However, the invisible pagelet will still be called. Returns true if the pagelet is currently minimized, otherwise returns false. To avoid unnecessary processing, template pagelets that can be invisible should always check this parameter before processing, and return immediately if false.

Note. This method should not be used for template pagelets without the CANBEINVISIBLE attribute set.