Using Scroll Areas, Scroll Bars, and Grids

This chapter provides an overview of scroll areas, scroll bars, and grids and discusses how to:

• Use scroll areas and scroll bars.

• Use grids.

• Configure embedded help for scroll areas and grids.

Understanding Scroll Areas, Scroll Bars, and Grids

A page must reflect the underlying table structures so that the system knows where to store data in the database. When you have more than one underlying record definition on a page, the role of scroll areas, scroll bars, and grids in page processing is important. Scroll controls and grids define parent and child record definition relationships on a page.

You assign an occurs level to each scroll control or grid on the page to indicate the relationship between the record definitions and the controls and to determine how the data is processed. The primary record on a page at level 0 has no scroll area or occurs level associated with it. If the page contains a record that is subordinate to the primary table, it has a scroll control with an occurs level of 1. A table that is subordinate to the level 2 record has a scroll area or grid with an occurs level of 2. PeopleTools does not support nesting beyond three levels.

PeopleSoft Application Designer automatically nests the scroll area after you set the occurs levels sequentially. Each field that you place on the page after each scroll area is automatically placed inside the scroll area preceding it until you place the next level-based control on the page.

Using Scroll Areas and Scroll Bars

This section provides an overview of scroll areas and scroll bars and discusses how to:

• Set scroll area general attributes.

• Set scroll area label properties.

• Set scroll area use properties.

• Set scroll bar label properties.

• Set scroll bar use properties.

• Control scrollable data.

• Convert scroll bars to grids.

Understanding Scroll Areas and Scroll Bars

Scroll areas, rather than scroll bars, are the preferred control for representing multiple rows of data from a table because they are easier to use during design time and offer a wider array of features. The final product at runtime appears more contained because the default setting places a border around the data.

The benefits of using scroll areas rather than scroll bars are:

• The navigation tools that you select for a scroll area are automatically positioned on the navigation bar or footer bar.

  For scroll bars, you must place these buttons and links on the page manually.

• Scroll areas provide the option of showing or hiding a border around the data.

• Scroll areas provide the option of a View All button and a Find feature.

• Scroll areas enable you to determine the text or image that appears for the action items in the navigation bars.

• Scroll areas provide a row separator when you select multiple occurrences of data.

Scrolls, Record Relationships, and Page Processing

A page must reflect the underlying table structures so that the system knows where to store data in the database. When you have more than one underlying record definition on a page, the role of scroll areas and scroll bars in page processing is important. Scroll controls define parent and child record definition relationships on a page.

You assign an occurs level to each scroll control on the page to indicate the relationship between the record definitions and the controls and to determine how the data is processed. The primary record on a page at level 0 has no scroll area or occurs level associated with it. If the page contains a record that is subordinate to the primary table, it has a scroll area with an occurs level of 1. A table that is subordinate to the level 2 record has a scroll area with an occurs level of 2. PeopleTools does not support nesting beyond three levels.

PeopleSoft Application Designer automatically nests the scroll area after you set the occurs levels sequentially. Each field that you place on the page after each scroll area is automatically placed inside the scroll area preceding it until you place the next level-based control on the page.

Scroll Areas

A scroll area looks like a group box with various controls. The title bar in a scroll area, however, can also serve as a navigation bar. The navigation bar gives the user various options for viewing the data. The plus and minus buttons in the body of the scroll enable the user to add and delete rows of data.

See Also

Level-Based Controls

Setting Scroll Area General Attributes

Assign the general attributes of a scroll area. These settings are the same for a scroll area as they are for a grid control.

See Setting Grid General Properties.

Manipulating Fields After Setting the Occurs Count

If you set the occurs count to a number greater than 1, you must reposition the fields in the scroll area. If you change the occurs count after placing fields in the scroll area, they might appear one on top of the other, very close together. Unless you indicate otherwise (in the body area of the Label tab), row separator lines might appear to distinguish one row from the next.

In the following example, the occurs count was set to 5 after placing one field, Access Group, in the scroll area. You must reposition the fields and possibly the labels so that they are evenly spaced in the row separator lines.

Before you do so, it is helpful to know a few rules about how you can move these fields in relationship to one another. For example, you do not need to move individual fields to their proper destination. For this example, we call the first field in the column of fields, or the original field that you placed in the scroll area, the head field. The fields following the head field are other occurrences.

• The head field controls the horizontal movement of all other occurrences that are below it.

• You cannot move the other occurrences horizontally.

• To evenly space the occurrences vertically, drag the last occurrence in the column to the appropriate position between the bottom edge of the scroll area and the last row separator.

  All occurrences above it reposition themselves equidistant from the others.

• You cannot move the add and delete push buttons (represented by the gray boxes on the right side of the scroll area) horizontally on the page.

  You can move them only vertically in the same manner as the fields.

After you move the lowest field, the scroll area should look similar to this:

Setting Scroll Area Label Properties

You can configure links or push buttons in three places on a scroll area to help users navigate through multiple rows of data in a scroll area. These options and the associated settings are the same as those for grids. This section references the setting definitions for grid controls that are described later in this chapter.

Header Area Properties

Use the header area properties to configure the title properties, navigation bar properties, and embedded help properties associated with the scroll area. These properties enable users to access controls for viewing the previous, next, top, or bottom row; to control the settings for the Find, Download, and View All features; and to access embedded help.

The Display Header check box is selected by default and enables access to Header Area properties. To disable the header, deselect the Display Header check box.

To configure title properties for the scroll area:

1. Select the Display Title check box.

2. Select the Left, Center, or Right title alignment option.

3. Click the Display Title Properties button to open the Title Properties dialog box.

4. Enter the Label Text that you want to appear in the scroll area title.

   Type	Select the type of label text to appear in the navigation bar. Message Catalog: Select this option to use a message in the Message Catalog as the grid title. Static: Select this option to enter manual text as the grid title.
   Text	Enter the text to appear as the title of the scroll area. This field is enabled when you select Static as the Label Text type.
   Message Set/Number	Enter the message set number and message number of the message in the Message Catalog to appear as the title of the scroll area. This field is enabled when you select Message Catalog as the Label Text type.

To configure navigation bar properties for the scroll area:

1. Select the Display Navigation Bar check box.

2. Select the Left, Center, or Right navigation bar alignment option.

3. Click the Display Navigation Bar Properties button to open the Header Navigation Bar Properties dialog box.

   The Header Navigation Bar Properties dialog box contains seven tabs, each pertaining to different settings on the navigation bar. Each tab has the same settings. All settings are set to display by default. Select the Invisible check box that appears in the upper right corner of each tab to hide the tab attribute from the user.

   This table describes the tabs in the Header Navigation Bar Properties dialog box:

   Top	Controls the attributes for how a user returns focus to the top of the grid or the first row of data in the grid. Text is the default setting using First from the Message Catalog. You can also enter static text.
   Previous	Controls how a user can move to a previous row in the grid. Image is the default setting, and the Show Previous Row button is the default image.
   Row Cntr (row counter)	Tracks the number of rows in the grid and in which row the cursor focuses. Text is the default setting, and, for example, 1–6 of 6 appears in the navigation bar if the grid has six rows. The Image Type is not enabled on this tab. Note. The row count that appears is controlled by the occurs count that you set on the General tab in the Grid Properties dialog box (unless the user displays all). Using the previous example, if the occurs count is set to 5, then the row counter is 1–5 of 6.
   Next	Focuses on the next row in the grid. Image is the default setting, and the Show Next Row button appears to the right of the row counter.
   Bottom	Controls the attributes for how a user moves focus to the last row of the grid. Text is the default setting using Last from the Message Catalog. You can also enter static text.
   Find	Displays a link that enables the user to search any field in the grid or scroll area. You can select either text or an image to represent the Find feature. The Find feature searches for matches in edit boxes, display-only fields, disabled fields, dynamic links, and text in long edit boxes. It does not search column headings, field labels, text values in icons, static links, and hidden fields, nor does it search outside the grid.
   View All	Enables the user to view all rows of data at once. Text is the default setting using View All as the Message Catalog entry.

To configure embedded help pop-up properties for the scroll area, use these options:

See Accessing Embedded Help.

View All Feature

The View All feature provides a threshold to enable the user to view the data in manageable pieces. If the database returns a number of rows for the grid or scroll area that is greater than the threshold, the View All link displays "View <threshold value>." This feature also modifies the occurs count and the values for the number of non-displayed rows left to scroll through.

The Next and Previous buttons retrieve rows according to the size of the threshold. If the database returns a total number of rows for the grid or scroll area that is less than the View All threshold, then the View All link on the navigation bar remains and functions as is.

The following example uses the View All threshold, occurs count, and total rows in database values:

• View All threshold = 100

• Occurs count = 10

• Total rows in database = 160

The result is:

When the user selects View 100, the view value changes to reflect the original occurs count set for the grid. The value for the number of non-displayed rows changes to 100 to match the View All threshold, and the View 100 display changes to View 10:

If the Occurs Count, which you define in the properties for grid and scroll areas, is set to a number greater than or equal to the view all threshold, then the threshold takes precedence. The View All display changes to View <threshold value> and the link is unavailable. If you select Unlimited Occurs Count, the grid or scroll area displays all rows in the buffer.

Body Area Properties

Use the body area properties to configure the row action buttons and set display properties for the body of the scroll area.

This table describes the Body Area properties:

Click the Row Action Buttons Properties button in the Body Area group box to open the Body Area Row Action Button Properties dialog box. It contains two tabs: Insert and Delete. The default settings for these tabs are to display the Insert and the Delete buttons. Alternatively, you can select static or message catalog text, or you can make these items invisible so that they do not appear.

Footer Area Properties

In the footer of your scroll area, you can display row action buttons and a navigation bar. To enable either of these features, select the appropriate check box, Display Row Action Buttons or Display Navigation Bar, and click the Properties button to configure the settings. Clicking the Properties button opens a separate dialog box: Footer Row Action Button Properties or Footer Navigation Bar Properties respectively.

The row action buttons are the same for the footer area as those described for the body area. The navigation bar property options are the same as those described for the header area. However, all other navigation bar settings for the footer are invisible by default.

Summary Properties

Summary properties enable you to provide a brief description of the functionality and content of the scroll area. This property is pertinent for users who access the application by using screen readers. The default value for the Summary Text field is the same as the Title of the scroll area. You can also enter static text or use the Message Catalog to store the summary information.

Access the Summary Properties dialog box.

This table describes the summary properties of the grid:

To change the Summary properties:

1. Click the Properties button located in the Summary group box.

2. Clear the Default to Title check box to activate the other Summary options.

3. Enter static text or enter a Message Set and Number to retrieve information from the message catalog.

4. Click the OK button.

5. Save the page.

See Also

Setting Grid Label Properties

Setting Scroll Area Use Properties

You can select several options to determine how you use the scroll area. As with the label properties, the settings on the Use tab of the Scroll Area Properties dialog box are the same as those on the Use tab of the Grid Properties dialog box, except that the scroll area contains fewer attributes than a grid.

When working with the row counter when designing pages in PeopleSoft Application Designer, consider the following:

• If the header area navigation bar is set to invisible, the system displays no header area navigation bar row counter button. Likewise, if the footer area navigation bar is set to invisible, the system displays no footer area navigation bar row counter button. If the row counter button of the header area navigation bar is set to invisible, the system displays no header area navigation bar row counter button.

• If the row counter button of the footer area navigation bar is set to invisible, no footer area navigation bar row counter button is displayed. Otherwise, if not set to invisible, the row counter button will be displayed as "|<< your_label >>|" where your_label is the specified text.

• If the text of the label is an empty string or the label refers to the message catalog with a message set of 0 and a message number of 0, then "your label" appears as an empty string and the label will be rendered as "|<< >>|".

See Also

Setting Grid Use Properties

Setting Scroll Bar Label Properties

To help identify scroll bars on the page definition, document the purpose of each scroll bar with an informational field label.

To specify a scroll bar label:

1. Access the Scroll Bar Properties dialog box.

2. Select the Label tab.

3. Enter the text label in the Text field.

   This label is for your information only—it doesn’t appear on the page. This label is useful for reordering page controls in the order list if you include a meaningful identifier in the label, such as the primary record definition for the scroll bar. For example, you might want to label it ABSENCE_HIST_SCROLL.

Setting Scroll Bar Use Properties

You set the scroll action buttons on the Use tab of the Scroll Bar Properties dialog box:

Access the Scroll Bar Properties dialog box. Select the Use tab.

Scroll Attributes

Field Use Options

Scroll Action Buttons

If you select a Scroll Action Button option, it appears on the page next to the scroll bar in PeopleSoft Application Designer. You must manually move it to the appropriate location on the page definition.

Controlling Scrollable Data

You can control scrollable data using the PeopleCode Data Buffer Access Classes.

See Accessing the Data Buffer.

Converting Scroll Bars to Grids

You can convert a single-level scroll bar to a grid control. PeopleSoft Application Designer provides a utility to automate this task. The Convert Scroll to Grid function:

• Designates the size and position of the grid as set to the area covered by the left-most label to the scroll bar.

• Issues warnings before deleting controls that are not supported by the grid.

• Converts radio buttons to drop-down list boxes.

• Sets label alignment of check boxes to center.

The conversion utility provides warnings for scroll bars that can’t be converted to grids due to grid control limitations. The conversion utility validates to the following limitations:

• No more than one grid can exist on a page.

• The scroll bar to be converted must not have any nested scroll areas or bars under it.

• The grid control must be the last control on the page.

• Radio buttons are not supported in grids and must be replaced with drop-down list boxes.

To convert a scroll to a grid:

1. Select the scroll bar.

2. Right-click and select Convert Scroll To Grid from the pop-up menu.

   This menu option is available only for scroll bars that can be converted. This utility searches for all page fields that are defined in the field order after the selected scroll bar control, up until the next scroll bar or scroll area control. It does the following for each field:

   • Confirms that the scroll control type can be displayed in a grid control.

   • Creates a grid column of the appropriate type.

   • Populates the attributes.

3. Click OK to display the new grid.

If any of the page fields cannot be displayed in a grid or if other problems are found, the utility displays an error message explaining why the scroll bar cannot be converted to a grid.

Using Grids

This section provides overviews of grids and discusses how to:

• Insert and resize grid controls.

• Insert and manipulate grid columns.

• Set column properties.

• Create a tabbed grid.

• Freeze grid columns.

• Use multiple grids on a page.

• Enable grid personalization.

• Set grid general properties.

• Set grid label properties.

• Set grid use properties.

Note. A specific type of grid called an analytic grid can be used exclusively for applications built for the PeopleSoft Analytic Calculation Engine.

See Also

Creating Analytic Grids

Understanding Grids

Scroll controls and grid controls function very similarly. Grids are more compact and display fields in a spreadsheet-like format. You insert page controls into a grid and associate the controls to record definitions, just as you do in a scroll control.

You can insert these page controls into a grid:

• Check boxes.

• Drop-down list boxes.

• Edit boxes.

• Long edit boxes.

• Push buttons or links.

• Images.

• HTML areas.

• Secondary pages.

• Subpages.

• Tab separators.

Note. When designing grids, use prompts in place of drop-down list boxes for better performance.

Understanding Grid Properties

When you accept the default settings of grids, the grid appears with :

• A data navigation bar at the top of the table that enables the user to page through additional rows of data.

• Delete and Add buttons at the end of each row that enable the user to insert and delete rows in the grid.

  The inserted row appears under the current row. These buttons appear automatically as determined by the grid properties (display-only, no row insert, and no row delete).

• An occurs count of 1.

  You can set the grid to be any size at design time and then set the occurs count to control the maximum number of rows to display at runtime.

There are three areas on a grid to which you can apply labels or image buttons to help the user navigate through the data in the grid. Set properties for these areas:

• Header

• Body

• Footer

Understanding Grid Personalization

PeopleSoft Application Designer enables the user to personalize a grid at runtime. By default, grid personalization is enabled. To change the default settings for grid personalization, open the Grid Properties dialog box and click the Display Navigation Bar Properties button. Grid personalization settings appear on the Personalize tab in the Header Navigation Bar Properties dialog box.

Note. If you do not display the grid header bar, the Personalize link is not available to the user unless you enable it for the footer area.

When the user clicks the Personalize link for a grid on a transaction page, the system opens the Personalize Column and Sort Order page, where custom parameters can be set for that grid. This page contains a sample grid that displays a few rows of real data from the buffer in display-only format. If there is no data in the buffer for that grid, only the column headings appear. Tabs in the grid are active so that the user can view all sample data.

From this personalization page, users can control the column and sort order, as well as copy other users' grid settings or choose to share their settings with other users once they save their changes.

The Column Order grid displays the columns in their current order, including tab separators. The list of fields is driven by the page definition but excludes columns that are hidden by PeopleCode. The user can hide columns and change their sort order. Users can also freeze grid columns. Columns that you freeze at design time automatically appear to the user as already frozen. However, the user has the option of overriding this setting.

The Sort Order grid enables the user to control the ascending and descending sort of each column, with the exception of tab separators, images, push buttons, links, and HTML areas. Users can sort hidden fields, however. The default setting is ascending for each column.

After making changes, the user can accept, preview, restore defaults, or cancel selections. If the user saves the new settings by selecting OK, the system stores the new settings as persistent values for that user based on a key structure. Therefore, each time the user accesses this grid, the system uses all personalization options that were set previously. The user can restore all default settings by selecting the Delete Settings link to remove all stored personalization settings from the database.

The user can override the persistent sort order directly on the transaction page by clicking the linked field label to affect the sort. Clicking the link repeatedly toggles between ascending and descending sort order for that column. This type of sorting directly in the transaction page is not persistent.

Note. You can continue to implement the SortScrolls PeopleCode command, but the user can override the defined sort with this feature.

Note. Modifying a grid or a page definition that contains a grid removes all runtime user personalizations associated with the modified page and the grid.

Inserting and Resizing Grid Controls

To insert a grid on a page:

1. Select Insert, Grid.

2. To adjust the grid width, drag the horizontal or vertical control handles.

   The horizontal grid width should be roughly equivalent to the columns that you insert into the grid. Otherwise, your grid might appear wider than necessary at runtime.

Inserting and Manipulating Grid Columns

This section discusses how to:

• Insert grid columns.

• Delete grid columns.

• Move grid columns on the Layout tab.

• Move grid columns on the Order tab.

• Resize grid columns.

Inserting Grid Columns

To insert a grid column:

1. Use one of these methods to insert a column:

   • Select a page control from the Insert menu or the page control toolbar and click the grid.

   • Drag a page field from inside the current page or from another page.

   • Copy and paste a page field or record field.

   • Drag a definition (such as a record field, a page field, or an entire record definition) from the project workspace.

     The new location of the definition or control is determined by the location of the upper left-hand corner of the drag rectangle, or by the mouse cursor if no drag rectangle appears. PeopleSoft Application Designer automatically places the first column on the left-hand side of the grid.

2. Click your mouse or release the field in the gray area of the grid.

   Place new columns to the right of existing columns by clicking or releasing the control in the gray area of the grid where no columns are present. To place a column between two grid columns, release the new column in the first of the two columns.

When inserting subpages into your grid as a column, be aware that:

• You can insert subpages by dragging them from the project workspace or by cutting and pasting from the page to the grid.

• Only one column displays in the grid in PeopleSoft Application Designer representing all fields in the subpage.

  At runtime, all fields display in the order they appear on the Order tab of the subpage.

• You cannot insert subpages that contain fields that are not allowed in grids such as static text or radio buttons.

  The system generates an error indicating the invalid field type. Similarly, if at a later point an invalid field type is added to a subpage already in a grid, the system generates a runtime error when the user accesses the page containing the subpage.

• The subpage you insert can contain fields that are associated with subrecord record fields.

  The same record name substitution mechanism that applies to subpages inserted onto a page applies to those inserted as grid columns. The system replaces the name of the subrecord as part of the expansion process and it is never seen at runtime.

  See Understanding Subpages.

Note. When inserting rich text enabled long edit boxes in grids, be aware that the long edit boxes must be display only. If the display only property is not enabled, unexpected results will occur.

Note. For scrollable grids that contain an HTML area column, the height of the grid is the product of the number of rows x 28 pixel default height per row; the grid height is not based on the data in the HTML area.

Deleting Grid Columns

To delete a grid column:

1. Select a column by right-clicking the column heading.

   Be sure that you select only the column and not the grid as a whole; otherwise, you might delete the entire grid instead of just the column. The grid is selected when control boxes appear around the edges of the grid. The column is selected when it turns black.

2. Select Delete from the pop-up menu.

Moving Grid Columns on the Layout Tab

To move grid columns on the Layout tab:

1. Select a column by clicking the column heading.

2. Drag the column to its new location.

3. Release the mouse button over the column that is to the left of the new location.

Moving Grid Columns on the Order Tab

To move grid columns on the Order tab:

1. Select the column row by clicking the row number.

   The grid and grid columns are clearly distinguished from other page fields on your page. The grid is identified by the Type column. All columns in the grid are directly below in a lighter green. Nongrid page field rows are white.

2. Drag the row to the new position in the grid.

   A red line indicates the new position of the column before you release it. You cannot move a column outside of the grid when working on the Order tab. Similarly, you cannot move an existing page field from elsewhere on the page into the grid. Both of these operations can be performed on the Layout tab.

Resizing Grid Columns

You can resize grid columns in PeopleSoft Application Designer by dragging the right border of the column heading.

Setting Column Properties

After you insert the page control or field into your grid, you can set the properties for that field as you would set properties for any other page control. Access the field properties by double-clicking the column heading.

Column headings and their alignment are derived from the label text that you select on the Label tab of the page field properties dialog box. The alignment of column contents is derived from the alignment settings on the Record tab of the page field properties dialog box. If alignment settings aren't available on the Record tab, then the system uses the Label alignment settings. For column headings, use the following guidelines for label alignment. Do not use colons in column labels.

Creating Tabbed Grids

Oracle recommends using a tabbed grid design if your grid contains many columns that extend past the right side of the page. Do this by adding tab separator controls to your grid.

You can give users the option of expanding all of the columns to the right so that they are visible when using the browser’s horizontal scroll bar. This is particularly useful to power users who do a great deal of intensive data entry. The Enable View All Columns check box on the Use tab in the Grid Properties dialog box controls this feature and is selected by default. The Expand All button appears to the right of the grid tabs, as shown in the preceding screen shot. After the grid is expanded, the Show Tabs button appears to enable the user to collapse the grid so that the tabs appear again.

Note. Each time the user moves to a new tab results in a transmission to the web server to display the next page.

To create a tabbed grid:

1. Insert a grid control on the page.

2. Insert the columns to appear on the first tab.

3. Insert a tab separator control after the last column.

4. Set the tab separator properties.

   1. Double-click the tab separator to access the Tab Separator Properties dialog box.

   2. Specify the label properties on the Label tab.

   3. Specify the general properties on the General tab.

5. Insert the next set of columns to appear on the second tab.

   Alternatively, you can place all of the columns in your grid first and then insert the tab separator between the two columns that you want separated.

6. Repeat steps 3 and 4 if necessary.

7. Set the tab separator properties by double-clicking the column heading of the tab separator.

   1. On the Label tab, specify the label type.

      Select None, Text, or Message Catalog. If you select Text, enter the label text and select the label alignment. The label text that you select appears on the tab in the grid.

   2. On the General tab, determine whether you want to enable the tab separator as a page anchor.

      If so, select the Enable as Page Anchor check box and enter a page field name.

8. Save the page.

Note. The grid tab must contain at least one non-frozen and visible column or the tab does not appear.

Freezing Grid Columns

You can freeze the first column or the first several columns in a tabbed grid so that they appear on subsequent tabs. To freeze more than one column, select the freeze option for each column that you want to appear on the following tab.

Freezing grid columns impacts the horizontal scrolling ability of the grid at design time. If you freeze a grid column that is not visible inside the boundaries of the grid at design time, you are not able to view all columns in your grid. Lengthen the width of your grid to accommodate all columns.

Freeze a grid column by selecting the Freeze Grid Column check box on the Use tab of the properties dialog box for that column. Note that the effects of selecting this attribute are visible only at runtime.

Using Multiple Grids on a Page

You can place as many grids on a page as you want, provided that they are at the same occurs level. They can be one above the other or they can be side-by-side, such as those in the following example. This is helpful when you must transfer data from one grid to another without switching between pages.

In the following example, the user can transfer data from the Source Competencies grid on the right to the Assigned Competencies grid on the left by using the double left arrow button. The push button is associated with a PeopleCode program, enabling it to transfer the data between the two grids.

As you can with other level-based controls, you can nest a grid in a scroll area or scroll bar. However, you cannot nest a grid in another grid.

Enabling and Disabling Grid Personalization

Grid personalizations are enabled by default. To disable grid personalization:

1. Open the Grid Properties dialog box.

2. Select the Label tab.

3. Click the Personalize button for the header navigation bar.

   This opens the Header Navigation Bar Properties dialog box.

4. Select the Personalize tab.

5. Select the Invisible check box.

6. Click the OK button.

To enable grid personalization in the navigation footer:

1. Open the Grid Properties dialog box.

2. Select the Label tab.

3. Select the Display Navigation Bar check box in the Footer Area group box.

4. Click the Properties button for the footer navigation bar.

   This opens the Footer Navigation Bar Properties dialog box.

5. Select the Personalize tab.

6. Clear the Invisible check box.

7. Click the OK button.

Setting Grid General Properties

Access the Grid Properties dialog box. Select the General tab.

Setting Grid Label Properties

Access the Grid Properties dialog box. Select the Label tab.

The Grid Properties, Label tab provides five main grid setting areas for you to configure:

• Header Area.

• Body Area.

• Column Headings.

• Footer Area.

• Summary.

Certain grid label properties such as label text and summary text can also be set through PeopleCode.

See Grid Class Properties.

Header Area Properties

Use the header area properties to configure the title properties, the navigation bar properties, and embedded help properties associated with the grid. These properties enable users to access controls for viewing the previous, next, top, or bottom row; to control the settings for the Find, Personalize, Download, and View All features; and to access embedded help.

The Display Header check box is selected by default and enables access to Header Area properties. To disable the header, clear the Display Header check box.

To configure title properties for the grid:

1. Select the Display Title check box.

2. Select Left, Center, or Right title alignment option.

3. Click the Display Title Properties button to open the Title Properties dialog box.

4. Enter the label text that you want to appear in the grid title.

   Type	Select the type of label text to appear in the navigation bar. Message Catalog: Select this option to use a message in the Message Catalog as the grid title. Static: Select this option to enter manual text as the grid title.
   Text	Enter the text to appear as the title of the grid. This field is enabled when you select Static as the Label Text Type.
   Message Set/Number	Enter the message set number and message number of the message in the Message Catalog to appear as the title of the grid. This field is enabled when you select Message Catalog as the Label Text Type.

To configure navigation bar properties for the grid:

1. Select the Display Navigation Bar check box.

2. Select Left, Center, or Right navigation bar alignment option.

3. Click the Display Navigation Bar Properties button to open the Header Navigation Bar Properties dialog box.

   The Header Navigation Bar Properties dialog box contains seven tabs, each pertaining to different settings on the navigation bar. Each of these tabs has the same settings. All settings are set to display by default. Select the Invisible check box that appears in the upper right corner of each tab to hide the tab attribute from the user.

   This table describes the tabs on the Header Navigation Bar Properties dialog box:

   Top	Controls the attributes for how a user returns focus to the top of the grid or the first row of data in the grid. Text is the default setting, using First from the message catalog. You can also enter static text.
   Previous	Controls how a user can move to a previous row in the grid. Image is the default setting, with the Show Previous Row button as the default image.
   Row Cntr (row counter)	Tracks the number of rows in the grid and in which row the cursor holds focus. Text is the default setting with, for example, 1-6 of 6 appearing in the navigation bar if there are six rows in the grid. The Image Type is not enabled on this tab. Note. The row count that appears is controlled by the occurs count that you set on the General tab in the Grid Properties dialog box (unless the user displays all). Using the previous example, if the occurs count is set to 5, then the row counter is 1-5 of 6.
   Next	Brings focus to the next row in the grid. Image is the default setting with the Show Next Row button appearing to the right of the row counter.
   Bottom	Controls the attributes for how a user moves focus to the last row of the grid. Text is the default setting, using Last from the message catalog. You can also enter static text.
   Find	Displays a link that enables the user to search any field in the grid or scroll area. You can select either text or an image to represent the find feature. The Find feature searches for matches in edit boxes, display-only fields, disabled fields, dynamic links, and text in long edit boxes. It does not find column headings, field labels, text values in icons, static links, and hidden fields, nor does it search outside the grid.
   View All	Enables the user to view all rows of data at once. Text is the default setting using View All as the message catalog entry.
   Download	Available for grids only. Displays a download image button in the header or footer bar that enables users to download all active, unhidden rows to a Microsoft Excel spreadsheet, regardless of how many rows are visible on the screen. The default for this setting in the header area is Invisible. For the footer area of a grid, the download button appears by default when you select the Display Navigation Bar check box in the Footer Area group box of the Label tab in the Grid Properties dialog box. Note. When you download a column of links comprised of numeric values, the values are downloaded as numbers instead of as quoted strings unless doing so causes Excel to modify the format of the numbers. Note. Microsoft Excel may display Unicode comma-delimited data differently because Microsoft Excel may be expecting a tab-delimited file. If display abnormalities occur, you have two options. In Microsoft Excel, after highlighting the first column, you can select Data, Text to Columns and select the options required to set Microsoft Excel to expect a comma-delimited file. Or, in PeopleSoft Application Designer change the file layout from comma-delimited to tab-delimited. Keep in mind that changing the file layout properties in PeopleSoft Application Designer could cause the data to change such that other applications may no longer recognize the data. Also, changing the file layout properties may impact more than one application, if that file layout is shared.
   Personalize	Available for grids only. Displays a Personalize link in the header bar that enables the user to access all grid personalization options. See Enabling and Disabling Grid Personalization.

To configure embedded help pop-up properties for the grid, select from these options:

View All Feature

The View All feature provides a threshold to enable the user to view the data in manageable pieces. If the database returns a number of rows for the grid or scroll area that is greater than the threshold, the View All link displays "View <threshold value>." This feature also modifies the occurs count and the values for the number of non-displayed rows left to scroll through.

The Next and Previous buttons retrieve rows according to the size of the threshold. If the database returns a total number of rows for the grid or scroll area that is less than the View All threshold, then the View All link on the navigation bar remains and functions as is.

The following example uses the View All threshold, occurs count, and total rows in database values:

• View All threshold = 100

• Occurs count = 10

• Total rows in database = 160

These values result in the following for the user:

When the user selects View 100, the view value changes to reflect the original occurs count set for the grid. The value for the number of non-displayed rows changes to 100 to match the View All threshold, and the View 100 display changes to View 10:

If the Occurs Count, which you define in the properties for grid and scroll areas, is set to a number greater than or equal to the view all threshold, the threshold takes precedence. The View All display changes to View <threshold value> and the link is unavailable. If you select Unlimited Occurs Count, the grid or scroll area displays all rows in the buffer.

Body Area Properties

Use the body area properties to configure the row action buttons and set display properties for the body of the grid.

This table describes the Body Area properties:

Click the Row Action Buttons Properties button in the Body Area group box to open the Body Area Row Action Button Properties dialog box. It contains two tabs: Insert and Delete. The default settings for these tabs are to display the Insert and Delete buttons. Alternatively, you can select static or message catalog text, or you can make these items invisible so that they do not appear.

Column Heading Properties

You can set the grid to display column headings, and you can select the style in which to display them. Select a predefined column heading style from the drop-down list box or use the default. Changing styles alters the foreground, background, and font in the column headings, making it different from the data rows. The default for Show Column Headings is selected.

Footer Area Properties

In the footer of your grid, you can display row action buttons and a navigation bar. To enable either of these features, select the appropriate check box, Display Row Action Buttons or Display Navigation Bar, and click the Properties button to configure the settings. Clicking the Properties button opens a separate dialog box: Footer Row Action Button Properties or Footer Navigation Bar Properties, respectively.

The row action buttons are the same for the footer area as those described for the body area. The navigation bar property options are the same as those described for the header area. However, all other navigation bar settings for the footer are invisible by default.

Summary Properties

Summary properties enable you to provide a brief description of the functionality and content of the grid. This property is pertinent for users who access the application by using screen readers. The default value for the Summary Text field is the same as the Title of the scroll area. You can also enter static text or use the Message Catalog to store the summary information.

Access the Summary Properties dialog box.

This table describes the summary properties of the grid:

To change the Summary properties:

1. Click the Properties button located in the Summary group box.

2. Clear the Default to Title check box to activate the other Summary options.

3. Enter static text or enter a Message Set and Number to retrieve information from the message catalog.

4. Click the OK button.

5. Save the page.

Setting Grid Use Properties

On the Use tab in the Grid Properties dialog box, you control data entry, row style, and display options, as well as whether your grid has a pop-up menu in the navigation bar at runtime. Both the grid and scroll area share many of the same attributes. Refer to the proceeding term tables for information about these shared settings.

Data Options

This table describes the data options properties:

Multirow Insert Option

Each time that a user adds a row to a grid or scroll area requires a transmission to the application server. With the multirow insert option, this transmission occurs only once when the user wants to add multiple blank rows. Selecting this option can significantly enhance the user’s experience when doing data entry and also meets the developer’s goal of limiting page processing.

At design time in PeopleSoft Application Designer, this feature is disabled by default. If the No Row Insert check box is selected, then the Allow Multi-Row Insert check box is deselected and disabled. Where the multirow insert button appears, in the row or in the footer, depends on how you define the grid or scroll area properties on the Label tab.

You can set any occurs count for your grid. When the end user inserts n rows, the occurs count for the grid or scroll area is temporarily increased to n + 1 (if necessary), showing one row of context plus the new rows. If you select an unlimited occurs count for the grid, this temporary adjustment is not necessary.

Note. This feature should not be enabled for grids and scroll areas with effective-dated rows.

When the user saves the page, normal save processing runs, including save-edits on all rows. New, unchanged rows are not saved. After save processing, new, unchanged (and unsaved) rows are deleted from the buffer. The only exception is when only one row exists and it is new and unchanged. This row remains in the buffer, even though it has not been saved, because a rowset must always contain one row.

For an end user, pressing the Alt+7 keys works the same with the multirow Add button as it does with the standard Add button.

Row Selection Indicator

These options enable the user to select one or more rows in the grid and scroll area. At runtime, indicators appear to the left of row numbers for grids and in the upper left corner for scroll areas. A transmission to the server triggers the selection of the row or rows that the user designates. These selections can then be detected in PeopleCode via the selected property on the row class for each row of data.

Note. For the row selection options, PeopleCode can change the selected property, which affects which boxes are selected when the page is regenerated.

Popup Menu

Select a preset pop-up menu from the drop-down list box. The pop-up menu button appears in the left-hand corner of the navigation header at runtime.

See Creating Pop-up Menus.

Row Styles

You can control the color, font, and other characteristics of a row, active tab, inactive tab, and navigation bar by specifying a style in the drop-down list box for each of the row style options.

Grid Style

These options enable the advanced grid properties available with scrollable grid layout only.

See Viewing Data in Scrollable Layout Grids.

Display Options

Configuring Embedded Help for Scroll Areas and Grids

You can configure scroll areas and grids to display an embedded help pop-up message that you create and store in the Message Catalog.

This diagram illustrates the business process flow for creating, configuring, and accessing embedded help:

Business process flow for creating and accessing embedded help

This section discusses how to:

• Enter embedded help messages in the Message Catalog.

• Associate help messages with scroll areas and grids.

Note. Use this information to configure embedded help for group boxes, also.

Entering Embedded Help Messages in the Message Catalog

To configure embedded help, first you must create Message Catalog messages that you specifically design for use by scroll areas and grids. To enter embedded help messages in the Message Catalog:

1. Access the Message Catalog (PeopleTools, Utilities, Administration, Message Catalog).

2. Select an existing or create a new message.

   Note. You should create new message sets to avoid extra upgrade maintenance tasks.

3. Enter the help content in the Explanation field. Include the necessary variables if you want to generate other help links that appear on the embedded help pop-up page. The table at the end of this section describes the variables and their usage.

   Note. The help content should be contextual and specific to the page control to which it will be associated in the next section.

4. Save the message entry.

Embedded Help Variables

This table describes the variables that you can add to the embedded help content in the Message Catalog. Use these variables to generate links on the embedded help pop-up page that enable the user to access additional online help.

Note. You must install the Online PeopleBooks Library for any PeopleBooks Online Help link to function properly.

%PBCTXT()

%PBCTXT(sn,mn)

%PBCTXT(CTXT_PG_NM)

%PBCTXT(CTXT_PG_NM, sn,mn)

%PBURLTBL(<URL_IDENTIFIER>⇒
,sn,mn)

%PBLNK(http://www.site.com⇒
,sn,mn)

See Also

Configuring General Portal Properties

Message Catalog

Associating Help Messages with Scroll Areas and Grids

After entering a message, you associate the message to a page control. To associate help messages to scroll areas and grids:

1. Open a page definition.

2. Double-click the scroll area or grid to access the properties dialog box.

3. Access the Label tab.

4. In the Embedded Help Popup section, select the Message Catalog Popup option.

5. Enter the Message Set/Number values of the message that you want to appear in the embedded help pop-up page.

   The message should appear in the Text field.

6. Verify that the message in the Text field is correct.

7. Click the OK button.

8. Save the page definition.

9. In the browser, access the page and test the embedded help.

Note. Use the preceding steps to associate Help messages to group boxes, too.

See Also

Accessing Embedded Help