7
Rebranding the Personalization Portal

This document explains the Personalization Portal architecture. Topics include:

• Overview

• Use Sequence

• Directory Structure

• Login Sequence

• Main Page Components

• Customization Components

• Customizing Services

• Customizing Folders

• Configuring Jobs

• Configuring the User Profile

• Debug Messages

• National Language Support

Overview

The Personalization Portal is a Web-based interface that allows end-users to manage their mobile device portals. At the Personalization Portal, users select the services that appear on their mobile devices, store frequently used parameters (such as email addresses and account numbers), and create notifications. Any change that a user makes at the Personalization Portal is immediately reflected on the users mobile device.

The Portal-to-Go Personalization Portal is both a framework for the personalization interface and a sample implementation of that framework. The framework consists of JavaServer Pages (JSP) files, JavaBean modules, JavaScript, and such static elements as images, style sheets, and HTML files. Another element of the framework is the logical sequence in which the elements execute. You can rebrand the Personalization Portal based on the existing framework or, by altering the logic in the JSP files and JavaBeans, restructure the framework itself.

The following sections acquaint you with the elements that generate the portal and their order of execution, as well as the file naming conventions and the directory structure used.

Use Sequence

A user accesses the Personalization Portal by entering a valid user name and password at the login page. The login page is generated by the JSP file, login.jsp.

If the user name and password is valid, the user's main page appears. The JSP file PapzMain.jsp generates the main page, which appears as follows:

The service tree provides an easy way for users to browse through their folders and services. The service view presents a desktop view of the user's folders and services. The service view includes links for invoking and editing services. The edit link allows users to customize their services. Users can add, move, and rename folders and services. For services, users can also create jobs (or notifications) and store service input values. For folders, users can also enable or disable services in that folder and create bookmarks.

When a user clicks the edit link for a service, for example, the following window appears:

When a user clicks a link in the Edit User Service window, a form appears where the user completes the action. For example, when a user clicks the Rename Service link, the following form appears:

The form contains instructions for renaming a service and a text field where the user enters a new value for the service name.

Note: The user must be the owner of the service to be able to change the service. You grant ownership privileges in the Service Designer. For a user, you would typically grant ownership to a service alias rather than the master service. For more information, see "Creating a Service Alias" in Chapter 5, "Portal-to-Go Services".

When finished, users click the Log Off button to close the Personalization Portal session.

Directory Structure

To rebrand the Personalization Portal, you modify the files that generate the Personalization Portal. After installing Portal-to-Go, these files are located in the papz directory. The papz directory has the following structure:

The directory contain the following:

Directory	Contents
papz	Container JSP files. Container files are accessed directly by browsers. They invoke Java beans and other JSP files. This directory also contains style sheets and JavaScript files.
papz/_pages/papz	The folder where the compiled pages are saved.
papz/images	Images used throughout the Personalization Portal.
papz/Web-inf/jsp	Module JSP files. These files are included by either container JSP files or other module JSP files. The edit and action JSP files are in this directory.
papz/oracle/panama/person	JavaBean modules.

Login Sequence

The login.jsp file generates the user login page. When the user clicks the Log In button, the flow moves to the loginAuthenticate.jsp file. The loginAuthenticate.jsp file validates the user. There are three possible results:

• If the user name and password are correct, the flow moves to the PapzMain.jsp file.

• If the user name or password are incorrect, an error message is displayed and the flow moves back to the login.jsp file.

• If the user is an administrator, the flow moves to the adminUserLogin.jsp file. This file generates an input form where the administrator can enter the user name of the end user whose account the administrator wants to manage. If the user name is correct, the flow moves to PapzMain.jsp (user home). If the user name is incorrect, the flow moves back to the login.jsp file.

The flow of a login action is displayed in the following figure.

Main Page Components

The JSP file PapzMain.jsp generates the Personalization Portal home page. PapzMain.jsp is a container file; it is accessed directly by browsers. It invokes other JSP files to generate each component of the main page. The following illustrates the files that generate the Personalization Portal home page.

topBar.jsp generates the function buttons at the top of the page. These buttons enable end users to change their profiles, log off, and invoke help. treeView.jsp, which is included by mainView.jsp, presents a tree view of the services available to the user. tableView.jsp provides a desktop view of folders and services, and includes links for editing service and folder attributes.

Customization Components

The edit and action JSP files execute the tasks associated with user customization:

• The edit JSP files, which begin with "ed", generate the forms for accepting user inputs.

• The action JSP files, which begin with "do", process user inputs, perform the action, and display the result.

For example, to rename a folder, Portal-to-Go first invokes edFolderRenameForm.jsp, then doFolderRename.jsp. The edit files are invoked by the JavaScript file papz.js.

Users can customize or configure the following:

• Services

• Folders

• Jobs (jobs, or notifications, alert users when preset conditions are met)

• Profile information

• Bookmarks

The following sections discuss the files that execute the customization and the sequences in which they execute.

Customizing Services

The edService.jsp file displays the Edit Service dialog, which allows users to customize their services. The dialog contains two frames:

• The top frame (edServiceMenu.jsp) displays the menu options available to the user.

• The bottom frame (insService.jsp) displays the instructions for all the menu options.

The following figure shows the edit service window.

Depending on the option selected by the user, an input form is displayed in the bottom frame by an edNameActionForm.jsp file. When the user clicks the Finish button on the input form, the flow moves to a doNameAction.jsp file. The doNameAction.jsp file posts and processes input values, and, depending on the validity of the input values, displays a success or an error message. The following figure displays the flow of control when a user edits a service.

The following lists the actions a user can perform in the Edit Services dialog and the corresponding JSP files.

Action	Description	Action JSP File	Do Action JSP File
Rename service	Rename a service	edServiceRenameForm.jsp	doServiceRename.jsp
Add service	Add a service by giving it a new name. The new service is always located at the current folder.	edServiceCreateForm.jsp	doServiceCreate.jsp
Move service	Move a service to a new folder.	edServiceMoveForm.jsp	doServiceMove.jsp
Create job	Create a job for a service by giving it a name, start date, start time, frequency, and an agent.	edJobForm.jsp	doJobCreate.jsp
Edit inputs	Save a set of values for running a service.	edServiceParamForm.jsp	doServiceSaveParam.jsp

Customizing Folders

The architecture of the edit folder files is similar to that of the edit services files. The edFolder.jsp frameset file invokes the Edit Folder dialog, which allows users to customize their folders. The dialog contains two frames:

• The top frame (edFolderMenu.jsp) displays the menu options available to the user.

• The bottom frame (insFolder.jsp) displays the instructions for all the menu options.

Depending on the option that the user selects in the top frame, the flow moves to a edNameAction.jsp file. This file displays an input form in the bottom frame. Once the user clicks the Finish button on the input form, the flow moves to doNameAction.jsp file. The doNameAction.jsp file posts and processes the input values, and, depending on the validity of the input values, displays a success or an error message.

The following lists the actions a user can perform in the Edit Services dialog and the corresponding JSP files.

Action	Description	Action JSP File	Do Action JSP File
Rename folder	Rename a folder.	edFolderRenameForm.jsp	doFolderRename.jsp
Add folder	Add a folder under the current folder.	edFolderAddForm.jsp	doFolderAdd.jsp
Move folder	Move a folder to any other folder under the root location.	edFolderMoveForm.jsp	doFolderMove.jsp
Edit folder content	Show, hide, or delete folders and services in a folder. The delete option takes precedence over the show or hide option.	edFolderListForm.jsp	doFolderContent.jsp

Configuring Jobs

Users can edit their jobs by clicking the Edit link corresponding to that job. The edJob.jsp frameset file displays the Edit User Jobs dialog. The dialog contains two frames:

• The top frame (edJobMenu.jsp) displays the options available to the user.

• The bottom frame (insJob.jsp) displays the instructions for all the menu options.

Depending on the option selected by the user, the input form in the bottom frame is displayed by the edNameActionForm.jsp file. When the user clicks the Finish button on the input form, the flow moves to a doNameAction.jsp file. The doNameAction.jsp file posts and processes the input values, and, depending on the validity of the input values, displays a success or an error message. The following displays the flow of control when a user edits a job.

The following lists the actions a user can perform in the Edit User Jobs dialog and the corresponding JSP files.

Action	Description	Action JSP File	Do Action JSP File
Rename job	Rename a job.	edServiceRenameForm.jsp	doServiceRename.jsp
Move job	Move a job to a new location. Users can choose either the up or down radio button to move the job up or down one level. Then, users can choose a location where they want to place the job.	edServiceMoveform.jsp	doServiceMove.jsp
Job content	Change the start date, start time, frequency, and agent for a job.	edJobForm.jsp	doJobCreate.jsp
Filter jobs	Specify a filtering condition for the job. Users select an output parameter from a drop-down list and add a filtering condition for that parameter.	edJobChangeForm.jsp	doJobChange.jsp

Configuring the User Profile

The edUserPref.jsp file is the frameset file that displays the Edit User Preferences dialog. This dialog consists of two frames:

• The top frame (edUserPrefMenu.jsp) displays the menu options available to the user.

• The bottom frame (insUserPref.jsp) displays the instructions for all the menu options.

The Edit User Preferences dialog allows users to perform two types of actions:

• Changing Password

• Configuring Agents

Changing Password

The edUserPref.jsp file displays the Edit User Preferences dialog. Once the user selects the Change Password option, the flow moves to the edPasswordChangeForm.jsp file. This file displays the input form for retrieving the old and new password from the user. Once the user clicks the Finish button on the input form, the flow moves to the doPasswordChange.jsp file. Depending on the validity of user input (old and new passwords), a success or error message is displayed. The following displays the flow of control when a user changes passwords.

Configuring Agents

Agents enable Portal-to-Go to transmit notifications to users. Notifications are alerts that are sent to a user's device to notify the user of a specific event, such as a stock reaching a target price, in the case of a stock service, or a flight delay, in the case of a travel service.

The edUserPref.jsp file displays the Edit User Preferences dialog, which allows users to perform the following actions. These actions are displayed in the top frame:

• Create an agent

• Specify a default agent

• Edit an agent

• Delete an agent

Depending on the action selected by the user, an input form is displayed in the bottom frame by an edNameActionForm.jsp file. When the user clicks the Finish button on the input form, the flow moves to a doNameAction.jsp file. The doNameAction.jsp file posts and processes the input values, and, depending on the validity of the input values, displays a success or an error message.

The following displays the actions a user can perform to manipulate agent information and the corresponding JSP files.

Action	Description	Action JSP File	Do Action JSP File
Create agent	Create an agent. Users need to specify a unique name for the agent, its address, and the device type.	edAgentCreateForm.jsp	doAgentCreate.jsp
Default agent	Select an agent as the default agent.	edAgentSelectForm.jsp	doAgentChange.jsp
Edit agent	Edit an agent's properties.	edAgentSelectFom.jsp, edAgent.jsp	doAgentChange.jsp, doAgentEdit.jsp
Delete agent	Delete an agent.	edAgentSelectForm.jsp	doAgentChange.jsp

Debug Messages

A debug feature in the Personalization Portal puts detailed information in the sys_panama.log file. The .jsp file initPRequst.jsp initializes the papzRequest bean. The last argument of the initialize method call is true or false, which indicates whether you want the debug messages to appear in the log file or not.

The default value is set to false. To get detailed debug messages, set the value to true. Because the initPRequst.jsp file is a component file that is included in other container files, you should change the timestamp of the container file (for example, PapzMain.jsp). After you make these two changes, detailed debug messages, with the correct timestamp, will be printed in the log file.

National Language Support

This release of Portal-to-Go supports single-byte, multi-byte, and fixed-width encoding schemes which are based on national, international, and vendor-specific standards.

Overview

If the character set is single byte, and that character set includes only composite characters, the number of characters and the number of bytes are the same. If the character set is multi-byte, there is generally no such correspondence between the number of characters and the number of bytes. A character can consist of one or more bytes, depending on the specific multi-byte encoding scheme.

A typical situation is when character elements are combined to form a single character. For example, in the Thai language, up to three separate character elements can be combined to form one character, and one Thai character would require up to 3 bytes when TH8TISASCII or another single-byte Thai character set is used. One Thai character would require up to 9 bytes when the UTF8 character set is used.

Multibyte Encoding Schemes

Multibyte encoding schemes are needed to support ideographic scripts used in Asian languages like Chinese or Japanese since these languages use thousands of characters. These schemes use either a fixed number of bytes to represent a character or a variable number of bytes per character.

Fixed-width Encoding Schemes

In a fixed-width multibyte encoding scheme, each character is represented by a fixed number of n bytes, where n is greater than or equal to two.

Variable-width Encoding Schemes

A variable-width encoding scheme uses one or more bytes to represent a single character. Some multibyte encoding schemes use certain bits to indicate the number of bytes that represent a character. For example, if two bytes is the maximum number of bytes used to represent a character, the most significant bit can be toggled to indicate whether that byte is part of a single-byte character or the first byte of a double-byte character. In other schemes, control codes differentiate single-byte from double-byte characters. Another possibility is that a shift-out code is used to indicate that the subsequent bytes are double-byte characters until a shift-in code is encountered.

Setting the Multi-Byte Encoding for the Personalization Portal

The portal gets the encoding for the text of the site from the setting in the PAPZ logical device, which is in the repository. The default encoding is ISO-8559-1, which is the standard for the Western European languages. The portal sets the content for each page with the encoding specified by the logical device. To change the default encoding to multi-byte encoding, which enables the display of various Asian languages, click PAPZ under Logical Devices in the Service Designer and change the encoding according to the IANA standards for your particular language.

Localization

To localize the display of information, you can modify the static text for the JSP pages in the Service Designer and the Personalization Portal.

Service Designer

To localize the Service Designer, you can modify the following local strings resource files:

• PASMException.properties (error messages)

• PASMSuggestion.properties (suggestions for some of the error messages)

• Resources.properties (labels for the Service Designer GUI)

These files are located in the directory:

...\Service Designer\classes\oracle\panama\pasm

Personalization Portal

To localize the Personalization Portal, you can modify the following local strings resource files:

• oracle\panama\personalization\jsp\resources\LocalStrings.properties

• oracle\panama\personalization\resources\LocalStrings.properties

These directories are extracted when you unzip panama_papz.zip.