Configuring Toolbars

This chapter provides an overview of the configurable toolbar and discusses how to:

Define toolbar buttons.
Configure toolbars.
Personalize toolbars.

Understanding the Configurable Toolbar

This section discusses:

Toolbar elements.
Delivered toolbars.
Delivered common toolbar buttons.

Toolbar Elements

There are four parts to the configurable toolbar:

Date Time/Time zone/History/Title area.
Button bar.
Component-specific summary data.
Toolbar footer.

History, Time Zone, and Title Area

The History and time zone drop-down list boxes, along with the page title, are presented at the top of the content area. Like the other tool bar elements, they are not required. This area can include the following elements:

Time zone controls

This includes current date and time information and a time zone selection field to display the date and time in various time zones.
History controls

This contains a list of previously viewed pages (from external components only), so that you can revisit them if necessary. To support the history control and be able to add the current transaction to the navigation history prior to performing a component transfer, specific code must exist on the previous component.
Page title

The page title, if enabled, is shown left-aligned on top of the toolbar buttons. If either the History or time zone field is enabled for the toolbar definition, it appears right-aligned on the same level as the page title. If both are enabled, the time zone field appears at the same level as the page title and beneath the History field.

Button Bar

The button bar is similar to a browser's toolbar. It can include the following elements:

PeopleTools actions

This includes buttons such as Save, Refresh, Add, Next in List, Previous in List, Return to Search, and Update/Display, which map to the corresponding buttons (which are available at the bottom of a page) that are defined in PeopleTools.
Custom actions

This includes buttons that perform application-specific actions, such as cloning a case. Often, clicking a custom button displays a page on which you complete the action.
The Personalize action

This enables users to reconfigure the buttons on the button bar.

You can choose which toolbar elements to display and, for PeopleTools and custom actions, you can define their appearance sequence. There are two kinds of toolbar buttons: primary and secondary. Primary toolbar buttons are orange-colored, rectangular buttons with text label on them. They always appear on the left of the toolbar, and cannot be hidden through user personalizations. Secondary toolbar buttons, on the other hand, can be configured to show only the button icon, the text label, or both. End users can hide secondary toolbar buttons through personalizations, if the buttons are configured to support this functionality in the toolbar definition.

Also, you can modify the delivered toolbar buttons' definitions, or you can create new toolbar buttons using application classes.

See Defining General Toolbar Attributes, Configuring Toolbar Buttons.

Component-Specific Data

Under the button bar, the toolbar displays summary information about the object that you are viewing. For example, the Case toolbar shows summary information about the current case. PeopleCode in the underlying component makes this information available.

When you configure a toolbar, you choose which and how summary data appear.

Toolbar Footer

If a page is too long to be displayed in a single browser window and you need to scroll to see the entire page, you can add a toolbar footer so that toolbar buttons are also available when users are at the bottom of the page. The toolbar footer is the same as the toolbar button area at the top of the page. One exception is that the footer has the Top of Page link instead of a Personalize link as you see in the header. When you click the right or left arrow for more buttons in either direction, the other toolbar shifts at the same time.

If you use display templates to render component pages, you can initialize the toolbar from the display template by referencing the toolbar definition ID in it (optional).

Subtabs

If you plan to use subtabs in pages, which are rendered by the toolbar framework, you need to define them in display templates. Subtabs are used to control the visibility of group boxes at the page level. For example, you can define subtabs in the Order component in such a way that a user who is completing an order form can jump easily from the billing section on the entry page to the interaction history section on the history page by selecting the section name from the Go To drop-down list box.

Subtabs that appear on CDM pages are not set up using the display template framework.

See Understanding Display Templates.

Delivered Toolbars

To obtain a list of toolbars that the PeopleSoft Customer Relationship Management (CRM) system delivers, and to identify the components, pages, and markets (global or industry-specific) that use them, go to the Toolbar Definition component and click Search without entering search criteria. The system displays all delivered toolbars on the Search Results list.

To review the buttons and display items that are available for use in toolbars, access the Toolbar Button Definition - Buttons page and the Toolbar Content Display Definition page of the selected toolbar definition.

Delivered Common Toolbar Buttons

This table lists the common button IDs that PeopleSoft CRM delivers and their usage:

Toolbar Button ID	Description
PT_ADD	Add. It is mapped to the Add button in PeopleTools.
PT_CORRECTION	Correct History. It is mapped to the Correct History button in PeopleTools.
PT_NEXT_IN_LIST	Next in list. It is mapped to the Next in List button in PeopleTools.
PT_NEXT_PAGE	Next page in the component.
PT_PREV_PAGE	Previous page in the component.
PT_PREVIOUS_IN_LIST	Previous in List. It is mapped to the Previous in List button in PeopleTools.
PT_REFRESH	Refresh page. It is mapped to the Refresh button in PeopleTools.
PT_RETURN_TO_SEARCH	Return to the search page. It is mapped to the Return to Search button in PeopleTools.
PT_SAVE	Save. It is mapped to the Save button in PeopleTools.
PT_SPELLCHECK	Spell check.
PT_UPDATE	Update/Display. It is mapped to the Update/Display button in PeopleTools.
PT_UPDATE_ALL	Update/Display all. It is mapped to the Update/Display All button in PeopleTools.
RB_360	Launch 360-Degree View.
RB_ADD_MODE	Add. For use with components that use custom add search pages.
RB_CLONE	Clone object.
RB_CONVERT	Convert object.
RB_CORRESPONDENCE_REQUEST	Send correspondence request.
RB_CTI_DIAL	CTI dialer.
RB_NEXT_IN_LIST	Next in list (used with configurable search). This button is hidden if you're viewing the last record in the list.
RB_NOTIFY	Send notification.
RB_PERSONALIZE	Personalize toolbar.
RB_PREV_IN_LIST	Previous in List (used with configurable search). This button is hidden if you're viewing the first record in the list.
RB_RETURN_TO_SEARCH	Return to search page (used with configurable search).
RB_SAVE	Save. Triggers the built-in DoSave() function in PeopleTools.
RB_SAVE_NOW	Save. Triggers the built-in DoSaveNow() function in PeopleTools.
RB_SEPARATOR	A separator image.
RB_UPDATE_MODE	Update. For use with components that use custom update search pages.
RB_UPSELL	Upsell.
RB_VIEW_WORKLIST	View worklist.

Before you add a custom button to the toolbar of a component, confirm that the component has the PeopleCode to support the action that the button performs. For instance, the RB_CLONE button does not work in the Service Order toolbar because the Service Order component does not have the code that is needed to support cloning.

For a complete list of system-delivered buttons (common and application-specific), access the Toolbar Button Definition component and perform search without entering any search criteria.

Defining Toolbar Buttons

To define toolbar buttons, use the Toolbar Button Definition component.

This section discusses how to:

Set up custom buttons
Define buttons

Page Used to Define Toolbar Buttons

Page Name	Object Name	Navigation	Usage
Toolbar Button Definition	RB_TB_BUTTON_DEFN	Set Up CRM, Common Definitions, Component Configuration, Toolbar Button Definition, Toolbar Button Definition	Define buttons for a toolbar.

Setting Up Custom Buttons

Before defining a new button to perform an application-specific action, check if it already exists as a system-delivered button by searching for it on the Toolbar Button Definition page. Button IDs that start with RB_ and PT_ are included in the system for delivered functionality, such as Save (PeopleTool-related) and Clone for cases and orders (component-related). You can give buttons alternate labels for application-specific usage when you define a toolbar.

Buttons that perform custom actions use application classes to execute the action. To create a custom button:

On the Toolbar Button Definition page, define the button.
On the Toolbar Definition page, add the button to the appropriate toolbar.
Implement the class method, which is specified in the button definition, in your application class.

This task is not necessary when creating buttons that perform standard PeopleTools actions or when modifying the appearance of delivered buttons.

Please refer to the following documentation for more information on application classes.

See Enterprise PeopleTools 8.45 PeopleBook: PeopleCode Reference

Defining Buttons

Access the Toolbar Button Definition page.

Toolbar Button ID

Displays the unique identifier of the toolbar button. This ID is referenced in PeopleCode to manipulate button properties.

Class Method

Enter the method name of the extended application class (the class that extends RB_TOOLBAR:Toolbar), which contains the PeopleCode that executes when a user clicks the button.

This value does not contain spaces or special characters.

Note. If you specify a value in this field, leave the Defined Button field blank.

Defined Button

Select a button value if the button is mapped to a PeopleTools-delivered action. Values are Add, CTI Phone Launch, Correction, Next Page In Component, Next in List, Previous Page In Component, Previous in List, Refresh, Related Links, Return to List, Save, Spell Check, Update/Display, and Update/Display All. These actions are the same as the similarly named PeopleTools buttons that normally appear at the bottom of a page.

Note. If you specify a value in this field, leave the Class Method field blank.

Toolbar Label

Enter the default button label, which is used as a tool tip for the button at runtime.

Content Name and Disabled

Select the default icons that appear when the toolbar button is active and inactive. Select image definitions from the PeopleSoft image catalog. To use a custom graphic, you must add it to the catalog first.

Details

Enter a detailed description, such as usage and comments, about the button.

Please refer to the following documentation for more information on using and creating image definitions for buttons.

Configuring Toolbars

To configure toolbars, use the Toolbar Definition component.

This section discusses how to:

Define general toolbar attributes.
Configure toolbar buttons.
Configure component-specific toolbar content.
Specify the default cursor position for pages.
Define toolbar system data.
View the runtime toolbar.

Pages Used to Configure Toolbars

Page Name	Object Name	Navigation	Usage
Toolbar Definition - Description	RB_TOOLBAR_DEFN	Set Up CRM, Common Definitions, Component Configuration, Toolbar Definition, Description	Define general toolbar attributes.
Toolbar Button Definition	RB_TOOLBAR_BTNS	Set Up CRM, Common Definitions, Component Configuration, Toolbar Definition, Buttons	Configure toolbar buttons.
Toolbar Content Display Definition	RB_TOOLBAR_DISP	Set Up CRM, Common Definitions, Component Configuration, Toolbar Definition, Content	Configure component-specific toolbar content.
Toolbar Focus Fields Definition	RB_TOOLBAR_FFLD	Set Up CRM, Common Definitions, Component Configuration, Toolbar Definition, Toolbar Focus Fields Definition	Specify the default cursor position for pages.
Toolbar Definition - System Data	RB_TOOLBAR_SYSD	Set Up CRM, Common Definitions, Component Configuration, Toolbar Definition, System Data	Define toolbar system data.

Defining General Toolbar Attributes

Access the Toolbar Definition - Description page.

Toolbar ID

Displays the toolbar's unique identifier. This ID is referenced in PeopleCode to manipulate toolbar properties.

Toolbar Details

Toolbar Page Title	Enter a page title that is displayed on the left side of the page above the toolbar buttons. A page title is not a required toolbar element, but it is recommended.
Display Page Title	Select to have the page title displayed. The default state for page title is set to On. Page title can be set dynamically through PeopleCode.
Description	Enter a description of the toolbar (for example, the name). This is a required field that is used to help users identify the toolbar on the Toolbar Definition component.
Show Date and Time	Select to have the date and time (in the user's time zone) appear on the toolbar when the user accessed the component associated with the toolbar. Note. If you select to show either date and time, or time zone, or both, the information appears at the same level as the page title. If the History drop-down list box is configured to be shown along with the date, time and timezone (the same level with the page title), the History drop-down list box is displayed above them on the top right hand corner of the page. If the date, time and timezone is not displayed but the History field is, it shows up at the same level with the page title.
Show Time zone Selection	Select to have a time zone selection drop-down list box appear on the toolbar with values defined in the Time zone Selection Codes field. This option enables end users to change the display time zone in the component based on the local or the user-defined timezone setting. Note. This functionality affects the display time zone only; it never affects underlying data.
Time Zone Selection Codes	This group box appears if you select the Show Time zone Selection check box.
Code and Prompt Value	Enter codes (for each displayed time zone) and corresponding prompt values for the time zone drop-down list box. Each code must be referenced by component-specific PeopleCode to be functional; do not modify delivered codes. Enter text for every code in the Prompt Value field that appears in the time zone selection field on the toolbar. You can modify the delivered prompt value text without affecting time zone processing. These are the system-delivered code and prompt value pairs for the Case components that are used in PeopleSoft Support and HelpDesk: A: The currently assigned agent. C: The caller. In PeopleSoft Support, this is a customer; in PeopleSoft HelpDesk, this is the employee. P: The previously assigned agent. U: The current user.
Display Option	Select Icon, Icon/Text, or Text. You can see about seven buttons on the toolbar at a time, if both the button and text are displayed. This number varies depending on the length of text and language used in the application. Grey vertical separators appear between each button. Text links are active links all the time, not just on the roll over state. Buttons are clickable as well as any space between the button and the text. Any remaining buttons can be accessed by using the << or >> button on the left and right side of the buttons. Only secondary buttons are scrollable; primary buttons always appear. When you scroll to the right, the last button to the right becomes the first button on the next scroll set. The same is true when you scroll to the left.
Width (in pixels)	Enter the width of the toolbar in pixels. The default toolbar width is set to 745 pixels.
Clone To	Enter the ID of the new toolbar that the system clones from the current toolbar when a user clicks the clone button on the toolbar of this page.

Toolbar Personalizations

Allow Toolbar Personalization

Select to allow toolbar personalization.

Personalizations

Displays the number of user personalizations that the toolbar currently has.

This information helps administrators to evaluate the usability of the current toolbar settings and to determine the impact that updating a toolbar has on users.

Reset Toolbar Personalizations

Click to delete any toolbar personalizations that users performed.

When changes to the toolbar functionality occur, administrators can use this button to refresh users' toolbar settings.

Toolbar Summary Area Layout

Summary Layout	Select Column or Row. The summary information area will be displayed under the button bar only after a customer or contact has been selected. Depending on the application, the summary area may contain other information besides customer information. The information in the content area is displayed in a two-column format, with the number of fields being configurable.
# of Columns	You can select a one or two column display if you select columns for the summary layout. The recommended number of columns is 2.
Width Type	Define the width of the columns using either a pixel or percentage amount.
Column 1 Width and Column 2 Width	Enter the width of the item display area in pixels or as a percentage of the total toolbar width. If pixel is used, be sure that the width of all columns adds up to 745 pixels. If percentage is used, be sure that the width of all columns does not exceed 100%.

Toolbar Control Properties

Select to have the toolbar footer, PeopleTools buttons, and PeopleTools links displayed. It is suggested that you disable the PeopleTools buttons and links from being displayed because it may cause confusion to users if the button used for the same function appears twice on a page. When using a new toolbar, it is recommended that you disable the PeopleTools generated folder tabs from the component property settings.

Configuring Toolbar Buttons

Access the Toolbar Button Definition - Buttons page.

Primary toolbar buttons are displayed in orange, rectangular shape without graphic representation; secondary toolbar buttons can be displayed in text, icon, or both.

Seq (sequence)	Enter sequence numbers to determine the order of the toolbar buttons.
Button Name	Select the button to place on the toolbar. Buttons that perform custom actions cannot necessarily be shared between components. For example, you cannot add the case Send Notification button to the Solution toolbar, because the PeopleCode behind the button is case-specific. Use the separator image (a vertical line) as needed to group buttons.
User Can Hide	Select to allow users to show or hide the button from the toolbar on the Personalize Toolbar page. You may not want to give users the ability to manipulate the visibility of some basic yet important toolbar functions, such as Save or Add. In this case, clear the check box of these buttons. These buttons become required buttons that users cannot manipulate on the Personalize Toolbar page. They always show up in the toolbar.
Text Label	Specify the text that is displayed on the button (for primary toolbar buttons) or next to the button (for secondary toolbar buttons) if the toolbar is configured to show both button icon and text.
Alt. Label (alternate label)	Enter the text that users can see if they put the mouse over the button.
Access Key	If you enter an access key, the keyboard shortcut Alt + access key brings the system focus to the associated button. Access key is disabled in toolbar footers.

Configuring Component-Specific Toolbar Content

Access the Toolbar Content Display Definition page.

Display Item ID

Enter the ID of the data to appear on the toolbar. The ID and the data that it references come from an array that component PeopleCode populates.

Row

Enter the toolbar row in which the content appears. Row 1 appears under the button bar. If you define display items for additional rows, those rows appear in order under row 1.

Item

Enter the position of the item in the row. Enter 1 for the item that appears in the leftmost position in the row, 2 for the next label to the right, and so forth.

Title

Enter a label for the item.

Width Pixels, Width %, Label Pixels and Label %

Enter the width of the display item label and data in pixels or as a percentage of the total toolbar width. If the latter, be sure that the total percentage for all fields on the same row does not exceed 100%. It is recommended that you indicate widths in percentage because the toolbar layout is adjusted automatically. The general guideline is 20% for the display item label, and 30% for the display item data. If pixel is used (for advanced HTML usage), the total width of all display items on the same row should add up to 745, which is the default toolbar pixel size.

Length of text

Enter the maximum number of characters of data (not label text) that can appear in this row. The text is truncated with the specified truncation token if it exceeds the length of text value, and is wrapped if it is too long for the width that you specify.

Truncation Token

Enter the characters that indicate truncated data. This appears when the data is longer than the value that you entered in the Length of text field.

Wrap Data

Select to wrap data if its length exceeds what is specified for the text length.

Start New Row

Select if the display item should start on the next new row.

Span Data

Select to let the display item span across horizontally to use the other column to display its long item value. This option is enabled only when Start New Row field is selected.

If display items are configured using the BO (business object) search adapter, the data that corresponds to these display items are automatically updated upon return from the BO search.

Specifying Default Cursor Position for Pages

Access the Toolbar Focus Fields Definition page.

For pages that uses the CRM toolbar, you can specify the field in which the cursor always appears when the page is rendered. The toolbar doesn't set the cursor position for any page that either doesn't have a focus field defined in the toolbar definition or its focus field doesn't exist on the page, for example, the button is hidden, or is removed from the page after the toolbar definition.

Component, Market, and Page Name

Enter the component and market of the page in which the selected toolbar definition is referenced. The component you enter determines the drop-down values for page names.

Record and Field Name

Enter the record where the focus field resides and the focus field itself. The record you enter determines the drop-down values for field names.

Multiple fields on the same page can be defined. This is useful when you want to set the cursor on a different field when the user enters the page in a different type of transaction mode. The toolbar always puts the cursor to the first editable, available field on the page.

Defining Toolbar System Data

Access the Toolbar System Data Definition page.

This page is used to determine which data should be migrated and installed for new database installation. Buttons checked for PS CRM Core will be available and installed for all products. However, if you want to make a toolbar button available only to a specific vertical solution, select the appropriate application.

Viewing the Runtime Toolbar

Access the page that has a configurable toolbar.

Confirm that the toolbar and all of its buttons work as intended. Note that the customer and contact values are links; click them and they system transfers you to corresponding business object records. If you change the value of these fields in the transaction, the update takes effect immediately on the toolbar summary area.

Personalizing Toolbars

End users can personalize which buttons appear on the toolbar. Personalized configurations are associated with user IDs and do not affect the base toolbar definition. As an administrator, you can decide (during setup) whether users can personalize toolbars, and specify which buttons in the toolbar can be hidden by users in the personalization process.

This section discusses how to set toolbar preferences.

Page Used to Personalize Toolbars

Page Name	Object Name	Navigation	Usage
Personalize Toolbar	RB_USER_TB_PRSN	Click the toolbar's Personalize link on the page whose toolbar you want to personalize.	Set toolbar preferences.

Personalizing the Toolbar

Access the Personalize Toolbar page.

Note. If the Personalize link is not present on a toolbar, then that toolbar is not user-configurable.

Select Controls

Users can move buttons from Available Controls to Selected Controls for them to be displayed on the toolbar. In addition, the user can choose to view icons or text or both. Buttons with an asterisk are not subject to user personalization. They always show up in the toolbar.

After making some changes, click the Preview button to view the toolbar updated in real time.

Upon return from the page, the Personalized setting is automatically saved.

Toolbar Button ID	Displays the unique identifier of the toolbar button. This ID is referenced in PeopleCode to manipulate button properties.
Class Method	Enter the method name of the extended application class (the class that extends RB_TOOLBAR:Toolbar), which contains the PeopleCode that executes when a user clicks the button. This value does not contain spaces or special characters. Note. If you specify a value in this field, leave the Defined Button field blank.
Defined Button	Select a button value if the button is mapped to a PeopleTools-delivered action. Values are Add, CTI Phone Launch, Correction, Next Page In Component, Next in List, Previous Page In Component, Previous in List, Refresh, Related Links, Return to List, Save, Spell Check, Update/Display, and Update/Display All. These actions are the same as the similarly named PeopleTools buttons that normally appear at the bottom of a page. Note. If you specify a value in this field, leave the Class Method field blank.
Toolbar Label	Enter the default button label, which is used as a tool tip for the button at runtime.
Content Name and Disabled	Select the default icons that appear when the toolbar button is active and inactive. Select image definitions from the PeopleSoft image catalog. To use a custom graphic, you must add it to the catalog first.
Details	Enter a detailed description, such as usage and comments, about the button.

Display Item ID	Enter the ID of the data to appear on the toolbar. The ID and the data that it references come from an array that component PeopleCode populates.
Row	Enter the toolbar row in which the content appears. Row 1 appears under the button bar. If you define display items for additional rows, those rows appear in order under row 1.
Item	Enter the position of the item in the row. Enter 1 for the item that appears in the leftmost position in the row, 2 for the next label to the right, and so forth.
Title	Enter a label for the item.
Width Pixels, Width %, Label Pixels and Label %	Enter the width of the display item label and data in pixels or as a percentage of the total toolbar width. If the latter, be sure that the total percentage for all fields on the same row does not exceed 100%. It is recommended that you indicate widths in percentage because the toolbar layout is adjusted automatically. The general guideline is 20% for the display item label, and 30% for the display item data. If pixel is used (for advanced HTML usage), the total width of all display items on the same row should add up to 745, which is the default toolbar pixel size.
Length of text	Enter the maximum number of characters of data (not label text) that can appear in this row. The text is truncated with the specified truncation token if it exceeds the length of text value, and is wrapped if it is too long for the width that you specify.
Truncation Token	Enter the characters that indicate truncated data. This appears when the data is longer than the value that you entered in the Length of text field.
Wrap Data	Select to wrap data if its length exceeds what is specified for the text length.
Start New Row	Select if the display item should start on the next new row.
Span Data	Select to let the display item span across horizontally to use the other column to display its long item value. This option is enabled only when Start New Row field is selected. If display items are configured using the BO (business object) search adapter, the data that corresponds to these display items are automatically updated upon return from the BO search.