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.
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.
Image: Example of a scroll area
This example illustrates the fields and controls on the Example of a scroll area. You can find definitions for the fields and controls later on this page.
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.
Image: Multiple occurs counts in a scroll area
This example illustrates the fields and controls on the Multiple occurs counts in a scroll area. You can find definitions for the fields and controls later on this page.
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:
Image: Fields moved to accommodate multiple occurs counts
This example illustrates the fields and controls on the Fields moved to accommodate multiple occurs counts. You can find definitions for the fields and controls later on this page.
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 topic.
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:
Select the Display Title check box.
Select the Left, Center, or Right title alignment option.
Click the Display Title Properties button to open the Title Properties dialog box.
Enter the Label Text that you want to appear in the scroll area title.
Field or Control
Definition
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:
Select the Display Navigation Bar check box.
Select the Left, Center, or Right navigation bar alignment option.
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.
Image: Header Navigation Bar Properties dialog box
This example illustrates the fields and controls on the Header Navigation Bar Properties dialog box. You can find definitions for the fields and controls later on this page.
This table describes the tabs in the Header Navigation Bar Properties dialog box:
Field or Control
Definition
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.
Note: The system ignores fields in HTML areas when running a Find request.
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:
|
Field or Control |
Definition |
|---|---|
| No Popup |
Select this option to disable embedded pop-up help. This value is the default. |
| Message Catalog Popup |
Select this option to enable the embedded pop-up help icon on the grid at runtime. Selecting this option enables the Message Set/Number edit boxes. |
| Message Set/Number |
Enter the message set number and message number of the message catalog entry to appear when the user clicks the embedded help icon. |
| Text |
Displays the message that appears when the user clicks the embedded help icon. This field is display-only. |
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:
Image: Viewing 10 rows
This example illustrates the fields and controls on the Viewing 10 rows. You can find definitions for the fields and controls later on this page.
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:
Image: Viewing 100 rows
This example illustrates the fields and controls on the Viewing 100 rows. You can find definitions for the fields and controls later on this page.
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:
|
Field or Control |
Definition |
|---|---|
| Row Action Buttons |
Select to display Insert and Delete buttons on each grid row at runtime. The action buttons can appear on the left or right side of the scroll area. Click the Properties button to open the Body Area Row Action Button Properties dialog box. |
| Background Style |
Select a background style to display for the scroll area as a whole. The style selected here applies to all areas of the scroll area that are not covered by other elements. |
| Show Border |
Select to display a standard border around your scroll area. The default is selected. |
| Show Row Separator |
Select to display vertical separator lines between rows when multiple rows are returned from the database. The default is selected. |
| Adjust Layout for Hidden Fields |
Select to have the scroll area adjust its borders to accommodate any hidden fields. Note: For the scroll area to adjust automatically, the hidden fields inside the scroll area must be surrounded by open space or have other hidden fields to the right or left. |
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.
Image: Body Area Row Action Button Properties dialog box
This example illustrates the fields and controls on the Body Area Row Action Button Properties dialog box. You can find definitions for the fields and controls later on this page.
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.
Image: Summary Properties dialog box
This example illustrates the fields and controls on the Summary Properties dialog box. You can find definitions for the fields and controls later on this page.
This table describes the summary properties of the grid:
|
Field or Control |
Definition |
|---|---|
| Default to Title |
Select this check box to have the summary property the same as the grid title. Clear this check box to activate the Text and Message Catalog options. |
| Text |
Select this option to enter up to 254 characters in the Summary Text field. Selecting this option disables all Message Catalog option related fields. |
| Message Catalog |
Select this option to choose a message stored in the Message Catalog. Selecting this option disables all Text option related fields. Select one of these two options:
|
To change the Summary properties:
Click the Properties button located in the Summary group box.
Clear the Default to Title check box to activate the other Summary options.
Enter static text or enter a Message Set and Number to retrieve information from the message catalog.
Click the OK button.
Save the page.
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 "|<< >>|".
Note: Scroll bars are not supported in fluid applications.
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:
Access the Scroll Bar Properties dialog box.
Select the Label tab.
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.
Note: Scroll bars are not supported in fluid applications.
You set the scroll action buttons on the Use tab of the Scroll Bar Properties dialog box:
Image: Specifying scroll bar Use
This example illustrates the fields and controls on the Specifying scroll bar Use. You can find definitions for the fields and controls later on this page.
Access the Scroll Bar Properties dialog box. Select the Use tab.
Scroll Attributes
|
Field or Control |
Definition |
|---|---|
| Occurs Level |
Having an occurs level for the scroll bar enables you to designate the hierarchical parent and child relationship. Entering 1 specifies that the scroll bar is at the first level. Entering 2 specifies that a scroll is at the second level and is a child of, or nested in, the first level of data, and so on up to 3. A scroll can be nested in another scroll or scroll area, but it cannot be nested in a grid. See Level-Based Controls. |
| Occurs Count |
Enter the number of rows to appear at one time in the grid at runtime. See Level-Based Controls. Note: Always reorder your controls, if necessary, before you enter an occurs count. |
Field Use Options
|
Field or Control |
Definition |
|---|---|
| Invisible |
Select to make the scroll bar invisible. |
| Default Width |
This does not apply because the scroll bar does not appear on the page at runtime. |
| No Auto Select |
Select to prevent the system from retrieving data automatically from the database. Select to populate the scroll bar with data using the ScrollSelect PeopleCode functions. |
| No Auto Update |
Select to prevent the system from updating data automatically based on the existing key list. Select when the scroll bar contains work field controls that should affect only a page and not the underlying database. |
| No Row Insert |
Select to prevent the row insert function so that the user cannot insert new rows. |
| No Row Delete |
Select to prevent the delete function so that the user cannot delete rows. |
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.
|
Field or Control |
Definition |
|---|---|
| Previous Page |
Select to display a link that enables the user to move to the previous row or set of rows in the scroll buffer. |
| Row Insert |
Select to display a button that enables the user to add a row. |
| Top |
Select to display a link that enables the user to go to the first row of the scroll. |
| Show Row Counter |
Select to display a counter to show users what rows they are viewing and the total number of rows in the scroll bar, for example: <1 of 3>. |
| Next Page |
Select to display a link that enables the user to move to the next row or set of rows in the scroll buffer. |
| Row Delete |
Select to display a button that enables the user to delete a row. |
| Bottom |
Select to display a link that enables the user to go to the last row of the scroll bar. |
You can control scrollable data using the PeopleCode Data Buffer Access Classes.
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:
Select the scroll bar.
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.
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.