Using Page Controls

This chapter provides an overview of page controls and discusses how to use:

• Charts.

• Frames.

• Group boxes.

• Horizontal rules.

• Images.

• Static text.

• Check boxes.

• Drop-down list boxes.

• Radio buttons.

• Edit boxes and long edit boxes.

• Pop-up pages.

• Subpages.

• Secondary pages.

• HTML areas.

• Push buttons and links.

Understanding Page Controls

You use three categories of controls for page design and development. You determine which types of controls you want to add to your page definition by considering how you want to organize information on a page, as well as how your users will enter data.

This section discusses:

• Aesthetic controls.

• Data entry controls.

• Function and data processing controls.

Aesthetic Controls

Use aesthetic controls to help organize, display, or emphasize information on a page. Usually, aesthetic controls are not associated with a particular record field that is defined in a record definition and maintained in a database. With the exception of the image control, these controls never update data in the database. Aesthetic controls include:

Data Entry Controls

Use data entry controls to offer different ways to enter and maintain information. These types of controls are always associated with a record field that is defined in a record definition and maintained in a database.

Note. PeopleSoft Application Designer allows you add up to 405 fields on a page. When you reach this limit, typical system behavior includes being unable to select, move, or edit the page fields with an order number exceeding the 405-field limit. While this limit has no effect on the page at runtime, it has the potential to disrupt productivity during design time. If you find a page nearing the 405-field limit, you should use subpages to decrease the number of fields on a single page.

See Using Subpages.

Function and Data Processing Controls

Use function and data processing controls to provide a mechanism for running commands and to maintain levels of information on a page.

Using Charts

Use the Chart Properties dialog box to:

• Associate a chart with a record definition and record field.

• Assign a page field name.

• Set label attributes.

• Set the chart as a page anchor.

On the Label tab, add an information-only name for your chart. This label does not appear at runtime, but it does appear on the control order list on the Order tab of the page definition and any page definition report that you print. Assigning a label is helpful if you have multiple charts on your page.

See Also

GetChart

Using Frames

Use the frame control to visually group a set of controls on a page.

To change frame labels and display options:

1. Double-click a frame to open the Frame Properties dialog box.

2. On the Label tab, enter a brief text description of the function of the controls in the frame.

   The default frame label is Frame. Any label that you attach to a frame is for information only—it does not appear on your page, but it does appear on the page definition printout and in the control order list. Use labels to differentiate among multiple frames on your page.

   For example, if you are enclosing address controls, you might use the label Address Frame.

3. Select the style for the frame.

   You can control the line color and thickness and the background color of a frame by specifying a style.

   See Creating Style Sheet Definitions.

4. Select the Hide Border check box to hide the border of a frame.

   Use this option to use the style to shade only the background of the framed area or to apply other styles. If you select Hide Border, it overrides the border options that are specified in a style.

   You might also use a frame with a hidden border to facilitate HTML generation. When you insert a frame in a page section, the system generates that section as a table in HTML. This functionality is useful to ensure the correct layout. However, in some browsers, adding more HTML tables can degrade performance.

   See Improving Online Performance.

5. Select the Adjust Layout for Hidden Fields check box to enable automatic vertical adjustments to the frame size when hidden fields are present.

   If visible fields are not present to the right or left of the hidden field in a frame, the frame collapses to surround the remaining fields.

6. If the field is associated with multicurrency processing, select the Multi-Currency Field option on the Use tab in the Frame Properties dialog box.

   This selection causes the field to appear at runtime only if the Multi-Currency option on the PeopleTools Options page is selected.

Using Group Boxes

This section discusses how to:

• Insert and move a group box.

• Set group box properties.

Inserting and Moving a Group Box

To insert and move a group box:

1. Select Insert, Group Box.

2. Position the mouse where you want the initial location of the group box and click.

3. Move the group box to the appropriate location by clicking and dragging.

4. Adjust the group box size and shape using the handles on the edge of the group box.

5. Remove cursor focus from the group box by clicking anywhere outside of the group box in your page workspace.

Setting Group Box Properties

Use group boxes to visually associate relevant page field controls and to create a page that is intuitive to the user .

Setting Group Box Record Properties

Although the group box Record Field properties are optional, associating the group box with a record definition and record field enables you to:

• Distinguish individual group boxes when multiple group boxes appear on the page definition Order tab.

• Use PeopleCode to programmatically control the properties of the group box.

Access the Group Box Properties dialog box. Select the Record tab.

Setting the Group Box Label Properties

Use group box label properties to reflect how the fields that appear inside the group box are related.

However, if for visual reasons the group box surrounds a variety of disparate controls, you might manually enter a label rather than associating the group box with a record definition and field.

Access the Group Box Properties dialog box. Select the Label tab.

1. Select the label Type and select one of these options:

   Text	Select to manually enter the group box label. Selecting this option enables the Text field and disables the Label ID field. Note. You do not enter the text until the next step.
   RFT Short (record field text short)	Select to access the Short Name record field label properties of the record field that you associate with this group box. Selecting this option disables the Text field and enables the Label ID field. Note. You do not select the label until the next step.
   RFT Long (record field text long)	Select to access the Long Name record field label properties of the record field that you associate with this group box. Selecting this option disables the Text field and enables the Label ID field.

2. Select or enter the specific Label Text.

   Text	Enter or view the text that is to appear as the label in the group box header. If you select the RFT Short or RFT Long label type, the system automatically populates this field based on the Label ID that you choose and then disables it. Group box labels are limited to 50 characters, regardless of whether the label is static text or retrieved from the field definition.
   Label ID	Select the value that is to appear as the label in the group box header. The values that appear in this list depend on the label type option that you selected in the previous step and the label properties of the field definition. Changing the Label ID value automatically changes the value in the Text field. See Understanding Multiple Labels.
   Label Style	Select a value to determine the look and feel of the label. Note. Not all style classes are appropriate for labels. Changing the default style can produce unexpected results. See Overriding the Default Page Field Styles.

3. Select an Embedded Help Pop-up option.

   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.

4. Select an alignment option for the label.

5. Select the Display Options of the label.

   Body Style	You can control the color, line thickness, and background of the body section of a group box by specifying a style. See Creating Style Sheet Definitions.
   Hide Border	Select to hide the outside border of the group box. This selection overrides the border options specified in a style.
   Adjust Layout for Hidden Fields	Select to have the group box adjust its borders to accommodate any hidden fields. Note. For the group box to adjust automatically, the hidden fields inside the group box must be surrounded by open space or have other hidden fields to the right or left.

Setting Group Box Use Properties

Access the Group Box Properties dialog box. Select the Use tab.

Example of Collapsible Group Boxes

In the following example, the first group box, Spain, is expanded while the group boxes for France, Italy, and USA are collapsed:

Using Horizontal Rules

This section discusses how to:

• Draw a horizontal rule.

• Set horizontal rule properties.

Drawing a Horizontal Rule

To draw a horizontal rule:

1. Select Insert, Horizontal Rule.

2. Draw a horizontal line of the appropriate length on the page.

Setting Horizontal Rule Properties

This section discusses how to apply informational labels to a horizontal rule and configure how the horizontal rule is used on a page.

Setting Horizontal Rule Label Properties

To set horizontal rule label properties:

1. Open the Horizontal Rule Properties dialog box.

2. On the Label tab, enter an information-only label to differentiate the line from other frames and lines on your field order list.

3. Select the style for the line.

   You can control the color and line thickness of a horizontal rule by specifying a style.

   See Creating Style Sheet Definitions.

Setting Horizontal Rule Use Properties

Access the Horizontal Rule Properties dialog box. Select the Use tab.

Using Images

This section provides an overview of static images and discusses how to:

• Adjust static image size and shape.

• Set static image properties.

• Set image properties.

Understanding Static Images

A static image is different from an image because it:

• Does not change at runtime.

• Is not associated with a record field.

Static images are associated with a predefined image definition. For example, you might select a static image, such as a yellow Clear button, from the image catalog and place it on top of a push button control so that the user knows to click that button to clear the contents of the page.

Adjusting Static Image Size and Shape

You can adjust the size of a static image by dragging the handles on the edge of the image box , or you can adjust the size in the Static Image Properties dialog box on the Label tab by changing the width and height in pixels.

Setting Static Image Properties

To associate a static image with an image definition:

1. Open the Static Image Properties dialog box.

2. On the Label tab, select the label type.

3. If you select Text, enter a label to identify your static image.

   The label does not appear on your page at runtime. Use it to track your images in your scroll order list box and on page definition reports.

4. Select an image ID using one of the following methods:

   • Select a predefined image definition from the Image ID drop-down list box.

   • Click the Browse button next to Image ID to preview a list of available images.

     The Select Image dialog box appears with a list of the image components available. To the right of the list is a preview of the selected image.

5. Click OK to return to the Static Image Properties dialog box.

   The image that you selected appears in the image area with its width and height displayed in pixels.

6. Set the format and size attributes for the image.

   Scale	Select to scale the image to the size of the frame that you set using the control selection handles or by the width and height that you enter. The scaling occurs when you view the page in a browser.
   Size	Select to display the image as is, regardless of the control size on the page.

7. Click OK.

   You can now position the static image anywhere on the page.

Note. You can define your own static images, such as your company logo, by creating a new image definition. After you create the image definition, you can then add your logo to a page using a static image control.

See Creating Image Definitions.

Setting Image Properties

To set image properties:

1. Open the Image Properties dialog box.

2. On the Record tab, select the record and field names with which this image field is associated.

3. Set the image format and size attributes.

   Scale	Select to scale the image to the size of the frame that you set using the control selection handles or by the width and height that you enter. The scaling occurs when you view the page in a browser.
   Size	Select to display the image as is, regardless of the control size on the page.

4. Specify the alignment of your image.

5. Select a style for the image.

Setting Image Label Properties

Be sure to assign an informational label to your image. Assigning an informational label to your image is especially important if your application works with screen reader software.

To document an image control with an informational label:

1. Enter a text description in the Alt tag for image region.

2. Select one of the following settings from the Type drop-down list box:

   None	Select if you do not want a label. The Text field becomes unavailable for entry.
   Text	Select to enter a custom label. This value is the default setting.
   Message Catalog	Select to use a preset message from the message catalog. The Message Set and Msg Number (message number) fields become available for entry.
   RFT Long (record field table long) and RFT Short (record field table short)	Select to use a preset label from the record field set on the Record tab. The Label ID drop-down list box becomes available for entry.

Setting Image Use Properties

The Use tab of the Image Properties dialog box is the same as for that of an edit box.

See Setting Use Properties.

Using Static Text

Access the Static Text Properties dialog box.

Label Text

Style

You can control the color, font, size, and other characteristics of the text by specifying a style.

See Creating Style Sheet Definitions.

Alignment

Set the horizontal alignment of your text control, as determined by the left-hand edge of the field. You can align controls to the left-of-center, centered, or to the right-of-center.

Use Tab

If a text item is associated with multicurrency processing, select the Multi-Currency Field option. This selection causes the text item to appear at runtime only if the Multi-Currency option on the PeopleTools Options page is selected.

Using Check Boxes

When you insert a check box on a page, it appears with a default label, Dummy Name, until you specify a record definition name and field name, or a text label.

Setting Check Box Properties

Define the check box control by assigning the appropriate properties.

Setting Check Box Record Properties

To link check boxes with associated record definitions:

1. Open the Check Box Properties dialog box.

2. On the Record tab, select the record and field names from the drop-down list boxes.

3. Enter the enabled and disabled values for the check box.

   For example, if the enabled value of the check box is Y for yes and the check box is selected when the user saves the row, then the Y value is written to the database. If the disabled value of the check box is N for no and the check box is deselected when the user saves, then the N value is written to the database.

   The enabled and disabled values that you enter validate against the Translate table. If the system does not find a value, it displays a warning message but allows the value to remain. You might find this functionality useful when you create prototype pages before defining record definitions.

Setting Check Box Label and Use Properties

After you link the check box to a record definition and field, set the label properties. Otherwise, the default check box label is the field long name. Set how the check box will be used on the Use tab.

See Also

Setting Page Field Properties for Controls

Setting Use Properties

Using Drop-Down List Boxes

This section discusses how to:

• Set drop-down list box record properties.

• Set drop-down list box label and use properties.

Setting Drop-Down List Box Record Properties

To set drop-down list box record properties:

1. Open the Drop-Down List Box Properties dialog box.

2. On the Record tab, associate the drop-down list box with a record and field.

3. Select a style.

   Set the font and color attributes of your drop-down list box data.

   See Creating Style Sheet Definitions.

4. Select a displayed text option:

   • Xlat Short.

   • Xlat Long.

   • Prompt Table Field.

5. If you selected Prompt Table Field, enter the field name in the Prompt Table Field area.

6. Set the field size for the drop-down list box.

Setting Drop-Down List Box Label and Use Properties

You can set the label and use properties for a drop-down list box.

See Also

Setting Label Properties

Setting Use Properties

Using Radio Buttons

This section provides an overview of radio buttons and discusses how to:

• Set radio button record properties.

• Set radio button label properties.

• Set radio button use properties.

Understanding Radio Buttons

When you insert a radio button on a page, it appears with the default label, Dummy Name, until you specify a record definition name, field, and value for the radio button. Like edit box labels, radio button labels display a dashed box to indicate the translation buffer.

For radio buttons to function as a single group, they must be associated with the same record field and they must be adjacent fields on the Order tab of the page definition. To save time, add all radio buttons in a set, one after the other. After you add the first radio button, the system remembers the record definition name and field name for all subsequent radio buttons; you must enter only the database value for each. Then, place a group box around all of your radio buttons to keep them together and labeled, as in this example:

Setting Radio Button Record Properties

To link a record with radio buttons:

1. Open the Radio Button Properties dialog box.

2. On the Record tab, select the record and field name.

   The system retrieves the default label text if you enter the record or field.

3. Enter the database translate value for this radio button.

   In the preceding radio button example, N is for Normal. If you select the drop-down list box for the value, you see the translate value and the long name that was assigned to the field. When the user selects this radio button, it indicates a Normal value.

Setting Radio Button Label Properties

To set the label of a radio button:

1. Open the Radio Button Properties dialog box.

2. On the Label tab, select the type of label if it is other than the default of XLAT Long.

3. Select the radio button label location: to the left or right.

   See Setting Label Properties.

Setting Radio Button Use Properties

You might want to change the way that a radio button is used on a page. For example, you might want the selected value of a radio button to control what appears in another control.

See Setting Use Properties.

Using Edit Boxes and Long Edit Boxes

When you insert edit boxes and long edit boxes on a page, they appear with the default label, Dummy Name, until you specify a record and field for them or until you specify a text type field label. The space between the edit box label and the control is more than required: PeopleSoft Application Designer provides 25 percent extra space for the edit box label for translation purposes.

You control source data, labels, and how the control is used in the respective edit box and long edit box properties dialog boxes in PeopleSoft Application Designer. The settings for these two controls are mostly the same.

Note. Long edit boxes do not limit the number of characters that a user can enter in the browser, regardless of any limits defined in the underlying record field. As such, characters entered by the user that exceed the field length of the field definition may be truncated. For example, if you enter 012345678901234 into a long edit box associated with a field with a field length of 10, the input would be truncated and saved to the database as 0123456789. The system treats carriage returns (ASCII=13) and line feeds (ASCII=10) the same as any other character.

Mouse Over Pop-up Edit Boxes

You can associate mouse over pop-up pages with edit boxes. The pop-up page appears when you hover your mouse over any edit box that is pop-up enabled. You can identify edit boxes with mouse over pop-up pages associated with them because these edit boxes are both display-only and they appear with a dashed line beneath the control.

You can configure edit boxes to display pop-up pages at runtime by configuring properties on the Use tab at design time.

Display-Only Edit Boxes

Some edit boxes should be display-only. You might want a page field to govern what appears in another control. In some cases, you might want the page control to be invisible because it is required by PeopleCode but is not accessible by a user.

If you designate the long edit box as display-only, select the Expand Field When Display Only check box to hide the scroll and automatically expand the size of the edit box as necessary to display large amounts of text in the field.

You can configure controls to be display-only at runtime by configuring properties on the Use tab at design time.

Rich Text-Capable Long Edit Boxes

Some long edit boxes should display rich text format (RTF). RTF is a format type that enables cross-platform document interchange. At runtime, any long edit box that is rich text enabled appears with rows of text formatting toolbars, which enable you to specify formatting information in the text such as font; font size; font characteristics, such as bold and italic; margins; and so on.

You enable long edit boxes to display rich text at runtime by configuring properties on the Options tab at design time.

See Also

Setting Use Properties

Understanding Pop-up Pages

DisplayOnly

Using Pop-up Pages

This section provides an overview of pop-up pages and discusses how to:

• Define pop-up pages.

• Associate pop-up pages with fields.

• Enable Message Catalog pop-up pages.

Understanding Pop-up Pages

Pop-up pages are a type of PeopleSoft page that displays information that supplements, expands, or enhances the transaction page data. Pop-up pages are ideal for displaying additional, more detailed information that is pertinent to a subset of users. For example, you can create a Purchase Order Header Details pop-up page that displays customer details such as contact information and payment data. You can then associate the details pop-up page with the Purchase Order Line Items page so that an account representative who is reviewing line items can quickly access customer contact data without having to leave the transaction. Similarly, you can create an Employee Details pop-up page to display an employee's ID, name, department, current job assignment, phone number, and email address. You then associate the Employee Details pop-up page to a specific field on an employee-related transaction page. At runtime, when you move your mouse over this field, the pop-up page appears and displays information that is contextually relevant to the employee data on the transaction page.

Pop-up pages look and behave differently from standard PeopleSoft transaction pages. For example:

• Pop-up pages are not standalone pages; they are linked to, dependent upon, and accessed from their primary transaction pages.

• Pop-up pages do not appear unless you hover your mouse over the page control with which you associated the pop-up page.

• Pop-up pages support only a subset of page controls.

• Pop-up pages cannot contain scroll areas or grids.

• Pop-up page fields are display-only.

• You should place pop-up page PeopleCode either in the page Activate event or on the RowInit event of work records associated with the pop-up page.

• If a value at level 0 on the pop-up page comes from one of the search key fields and if no non-search key value from that record appears at level 0 on the main page, then RowInit PeopleCode in that record does not run.

  In addition, if a non-search key value from that record appears on the pop-up page only, then the system does not consider the field to be part of the main page. Because of this, no values for the non-search key fields are retrieved from the database. To populate non-search key fields on the pop-up page with data, you must place a non-search key value from that record on the main page. The field can be hidden on the main page, but it has to exist there.

Designing Context-Sensitive Pop-up Pages

To create pop-up pages that retrieve data that maintains the key field context of the main page, you must ensure that these conditions are met:

• For each record definition that the pop-up page references, key field values must exist on the main page.

• The names of the main page fields in which these key values exist must be identical to the names of the key fields of the record definitions referenced on the pop-up page.

  Note. While the field names must be identical, they do not have to be key fields in the record definition referenced by the main page.

• The fields in which the key values appear must appear in either the same scroll area as the field to which you associate the pop-up page or at a preceding level. The page field to which you link the pop-up page can be one of the fields that contains the key field values; frequently, it is the lowest order key.

Consider this scenario:

If PRec is the record that the pop-up page references and the key fields are PRec.K1 and PRec.K2, then, the K1 and K2 fields must exist on the main page as MRec.K1 and MRec.K2, where MRec is the record that the main page references.

If the field on the main page to which the pop-up page is attached is in ScrollA—a level one scroll area—then both MRec.K1 and MRec.K2 must either exist in ScrollA or at level zero.

Note. On the main page, it is not necessary that the K1 and K2 fields appear in the same record, MRec in the previous case. The fields could be MRec.K1 and NRec.K2, where NRec.K2 is some other field on the main page in the correct context.

Context-Sensitive Pop-up Page Example

In this example; you see a User Details pop-up page. This page is associated with a view, which retrieves information so that the page displays the employee's name, photo, department, phone number, address, and web site URL.

The fields on the pop-up page reference PS_EMPL_VW. The key field of PS_EMPL_VW is EMPLID, which requires that the EMPLID field exist on the main page.

The field to which the pop-up page is linked is at level 0, which requires that EMPLID be at level 0 also.

Note. EMPLID is a key field on the PS_EMPL_VW record that the pop-up page references. While EMPLID also happens to be a key field on the PS_EMPL_JOB record that the transaction page references, it is not a requirement.

Identifying Valid Controls on Pop-up Pages

You may insert these controls only on a pop-up page:

• Frames

• Group boxes

• Horizontal rules

• Static text

• Static images

• Check boxes

• Drop-down list boxes

• Edit boxes

• Images

• Long edit boxes

• Push Button/Hyperlinks

• Radio buttons

• Charts

Note. Except for Push Button/Hyperlink page controls, these controls are automatically set as display-only at runtime even if you do not set the Display-Only property on the control.

Using Push Buttons and Links on Pop-up Pages

You may use only these destination type values on a pop-up page:

• External link

• Instant messaging action

• Internal link

• PeopleCode command

• Process

• Secondary page

Note. Do not use other destination types for push button/hyperlink controls on pop-up pages because unexpected results will occur.

Defining Pop-up Pages

Before you define your pop-up pages, you should determine which data is appropriate for pop-up information. Typically, this is data that supplements and enhances the data on the primary page or information that you might access from more than one main page.

Note. When designing pop-up pages, carefully consider how to make them more versatile and reusable.

To define pop-up pages:

1. Select File, New and select Page from the New Definition dialog box.

2. Insert the record fields on the pop-up page.

3. Right-click the page and select Page Properties to open the Page Properties dialog box.

4. Select the Use tab.

5. Select Popup Page from the drop-down list box in the Page Type group box.

6. Select the page size:

   Auto-Size	Select to size the page automatically to fit the fields that are defined on it.
   Custom Size	Select to size the pop-up page by dragging the edge or by entering the width and height in pixels.

7. (Optional) Select Adjust Layout for Hidden Fields.

8. Click OK and save your pop-up page.

   If you selected Auto-Size, the system sizes the page automatically to fit the fields that are defined on it when you save.

Associating Pop-up Pages with Fields

To associate pop-up pages with fields:

1. Select File, Open and select the main page.

2. Select Insert, Edit Box or Insert Push Button/Hyperlink..

   Note. You can associate pop-up pages with display-only edit box and push button/hyperlink controls at level 0 or inside of scroll areas only. If you associate pop-up pages with controls that are in grids, you will receive an error.

3. Double-click the control.

4. Select the Use tab.

5. Select the Display Only check box.

6. In the Mouse Over Popup group box, select the Page Popup option.

7. Select the name of the pop-up page from the drop-down list box.

   Note. Only pop-up pages appear in the drop-down list.

8. Click the OK button.

   A dashed line should appear beneath the field to indicate its association with a pop-up page.

9. Save the page.

Note. If page controls are placed too close together on a page, the dashed line, which indicates an associated mouse over pop-up page, might not appear beneath the control.

Enabling Message Catalog Pop-up Pages

You can enable Message Catalog pop-up pages to embed context sensitive help on any PeopleSoft page. This section discusses how to:

• Enable message catalog pop-up pages.

• Embed context-sensitive PeopleBooks help in pop-up pages.

Enabling Message Catalog Pop-up Pages

To enable message catalog pop-up pages:

1. Double-click the field that accesses the pop-up page.

2. Select the Use tab.

3. Select the Display-Only check box.

   Note. You must select Display-Only.

4. Select the Message Catalog Popup option.

5. Enter the Message Set and Message Number of the message whose Message Text and Explain strings appear in the Message Catalog pop-up page.

6. Click the OK button.

Note. You can also set the Message Catalog entry for mouse over pop-up pages by using PeopleCode.

See MouseOverMsgNum, MouseOverMsgSet.

Embedding Context-Sensitive PeopleBooks Help in Pop-up Pages

You can add variables to a message to make a Message Catalog pop-up page context-sensitive to the PeopleBooks Online Library.

Note. You must correctly configure and implement PeopleBooks.

See PeopleBooks and the Online PeopleSoft Library, Managing the PeopleSoft Online Library and PeopleBooks, Integrating Context Sensitivity.

To add variables to messages to embed context-sensitive help:

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

2. Select an existing message or create a new message.

3. Enter an explanation and place the variable in the Explanation field.

   The table in the next section describes the variables and their usage.

   Note. The text in the Message Text field appears as the pop-up page header. The text in the Explanation field appears in the pop-up page body.

4. Enable the pop-up page on the desired edit box control.

   See Defining Pop-up Pages.

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. Your online PeopleBooks library must be installed 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)

Example

In this example, the %PBCTXT variable uses QRY_ADMIN as a CONTEXT_ID that references the Query Administration page in PeopleBooks:

In the Description field, the 4, 7 parameters refer to Message Catalog entry (4,7), which contains the label to use for the generated link.

On the Web Profile Configuration page at runtime, mouse over the selected control to see the generated pop-up page:

Notice that the pop-up text comes from Message Catalog entry (4,6) and the link label, Query Administration, defined by the %PBCTXT(QRY_ADMIN, 4, 7) function comes from Message Catalog entry 4,7. Click the Query Administration link, and the system accesses the PeopleBooks entry for the QRY_ADMIN CONTEXT_ID using that Help URL entry to ascertain the PeopleBooks location on the web server.

Note. You define the location of your online PeopleBooks by entering a URL in the Help URL field that is located on the Web Profile - General page (PeopleTools, Web Profile, Web Profile Configuration).

See Configuring General Portal Properties.

The result is the PeopleSoft Query PeopleBook topic that you see here:

See Also

Configuring Embedded Help for Scroll Areas and Grids

Using Subpages

This section provides an overview of subpages and discusses how to:

• Define subpages.

• Insert subpages into pages.

• Specify informational subpage labels.

Understanding Subpages

Subpages are a powerful means of factoring out commonly used page functionality in your application. Rather than duplicating the same set of page fields on two or more pages, you can create a single subpage that contains those page fields and then add it to any page. Subpages provide an easy way to maintain the functionality that the page fields represent.

Subpages are even more effective when used with corresponding subrecords. To support the use of subrecords with subpages, the system uses a record name substitution mechanism for subpage-type page fields. Each subpage has a from record that is determined dynamically by the page definition in PeopleSoft Application Designer and by PeopleSoft Pure Internet Architecture. The from record is a record associated with one of the page fields on the subpage. Which page field depends on the page field ordering, the types of page fields on the subpage, and whether the associated record is a subrecord. The subpage itself must be fully expanded to make this determination. (Keep this fact in mind when working with subpages that contain other subpages.)

You specify the to record in the SubPage Record Name Substitution group box in the Insert Subpage dialog box that appears after you insert the subpage into a page. (It also appears on the Subpage tab of the Subpage Properties dialog). At runtime, when a subpage-type page field is expanded, each page field that is associated with the dynamically determined from record is instead associated with the to record that you specify. For example, you can populate a subpage with page fields that are associated with a subrecord so that the subrecord is determined to be the from record; then, when that subpage is used as a subpage-type page field, you can specify the to record as one of the records that contains that subrecord. You are able to associate a single set of page fields (through the subpage) with a variety of different records (each containing the subrecord).

Defining Subpages

Creating a subpage is like creating a page definition except that you define it as a subpage rather than a standard page in the Page Properties dialog box.

To define a subpage:

1. Select File, New, Page.

2. Insert the record fields on the page.

   See Adding Page Controls.

3. Select File, Definition Properties to access the Page Properties dialog box.

   Use this dialog box to define the type, size, and layout of the page.

4. Select SubPage in the Page Type drop-down list box.

5. Select the size of the page.

   See Changing Page Use Information.

6. Select Adjust Layout for Hidden Fields if necessary.

7. Select Allow Deferred Processing if appropriate.

   See Understanding Processing Modes.

Inserting Subpages Into Pages

After you create a subpage definition, insert a subpage control on your primary page and associate it with the subpage definition.

To insert a subpage into a page:

1. Open the page into which you want to insert the subpage.

2. Select Insert, SubPage.

   The Insert Subpage dialog box appears.

3. Select a subpage definition.

   Specify the name of the subpage that you want to insert into the open page definition.

4. Select a record definition in the SubPage Record Name Substitution group box.

   The subpage writes its fields to a generic record. Specify the application-specific record name to which you want the information in the subpage written.

   See Using Subpages.

   Note. All of the fields in a subpage must be associated with fields of a subrecord in the specified record definition.

5. Click the OK button.

   The subpage appears on the page. Its size reflects the size of the page control group, and it is identified by the subpage definition name. During design time, the fields within the subpage are not visible. At runtime, pages containing subpages are dynamically expanded. Be sure to leave a few pixels of space between the left edge of the main page and the subpage page field to ensure sufficient padding at runtime.

When saving a page with multiple subpages, be aware that you may receive a warning message if duplicate fields are present.

Inserting a Subpage Into a Grid

You insert a subpage into a grid as you would any other column.

See Inserting and Manipulating Grid Columns.

Specifying Informational Subpage Labels

Document the purpose of the subpage by changing its informational label. The default subpage label is Subpage. Any label that you attach to a subpage is for information only: it does not appear on the page, but it does appear on the page definition printout and in the control order list. Use labels to differentiate among multiple subpages on a page.

To specify informational subpage labels:

1. Open the Subpage Properties dialog box.

   Note that the Subpage tab displays the information that you entered on the Insert Subpage dialog box.

2. On the Label tab, enter your informational text label.

3. Enter the page field name in the General tab.

4. (Optional) Select Enable as Page Anchor if you want the subpage to serve as a jump destination on the page.

5. Click OK.

Using Secondary Pages

This section provides an overview of secondary pages and discusses how to:

• Define secondary pages.

• Insert secondary page controls.

• Associate secondary pages with primary pages.

Understanding Secondary Pages

Secondary pages are pages that you access through another page, usually by clicking a link or push button. Secondary pages are ideal for entering and updating data that is supplemental to the data on the primary page or data that is common to and can be accessed from multiple primary pages. While a secondary page might sometimes appear as just another page to the user at runtime, secondary pages have certain characteristics that are not shared with standard pages. For example:

• Secondary pages are not standalone pages that you access through the menu structure. You can only access a secondary page from its primary page; the primary page and the secondary page are associated by push button or link page controls.

• Secondary pages include OK and Cancel or Return buttons (or equivalent alternatives) so that the user can accept or discard input, dismiss the secondary page, and return to the primary page.

• Secondary pages display no component buttons, such as Save, Return to Search, and so on.

Example: Secondary Page

In this example, notice the Change password link on the General Profile Information page, which is the primary page:

When the application user clicks the link, it opens the Change password secondary page in the browser.

Secondary pages that open in the browser often are hardly distinguishable from standard pages, as you see in this secondary page example.

Click the Cancel button to discard any changes that you make on the secondary page. Click the OK button to accept any changes that you make on the secondary page. The new information that you enter on the secondary page is not saved when you click the OK button; you must save the component.

Understanding Modal Secondary Pages

Modal secondary pages do not appear in a browser window. Modal secondary pages appear in front of a browser window, capturing focus and disabling the primary page until you dismiss the secondary page.

You can move modal secondary pages by dragging the page title bar. Moving the page is useful when you want to view information on the primary page while working with the secondary page. The appearance of the cursor changes to indicate that you can move the page.

Use these guidelines to determine whether to specify secondary pages as modal. Specify a secondary page as modal when:

• The content of the secondary page is relevant to the context of the primary page.

  For example, you need to be able to see both the secondary page and primary page simultaneously.

• The content of the secondary page is such that the user can complete the transaction quickly and easily.

By default, secondary pages appear as modal pages. You can change the default behavior at the definition level by deselecting the Disable Display in Modal Window When Not Launched by DoModal Peoplecode check box that appears on the Use tab on the Page Properties dialog box of the secondary page. You also control secondary page modality by using the DoModal PeopleCode function.

See Defining Secondary Pages.

Example: Modal Secondary Page

As in the preceding example, the user clicks the Change password link to access the Change password secondary page. In this example, notice that the Change password secondary page is a modal page. It hovers above the Change Profile Information page, which is the primary page.

Defining Secondary Pages

Access the Page Properties dialog box for the page definition. (With the page open, select File, Definition Properties.)

To define secondary pages:

1. Select File, New and select Page from the New Definition dialog box.

2. Right-click the page and select Page Properties to open the Page Properties dialog box.

3. Select the Use tab.

4. Select Secondary Page from the Page Type drop-down list box.

5. Deselect the OK & Cancel buttons and the Close Box check boxes if you plan to develop alternative buttons that dismiss the page. To use the standard buttons, accept the default values.

   See Using Push Buttons and Links.

6. Select the page size:

   Auto-Size	Select to have PeopleSoft Application Designer size the page to accommodate the page controls that are defined therein. The right and bottom edges of the page move left and up, respectively, to eliminate any vacant space at the right side and bottom of the page. The top and left edges of the page are stationary, leaving any vacant space at the right side and bottom of the page.
   Custom Size	Select to manually size the secondary page by dragging the edges or by entering the width and height in pixels.

7. Select the page style sheet to associate with the secondary page.

   To override the application default style sheet, select a different style sheet from the drop-down list box. The style sheet that you select is available only for the controls on the secondary page.

8. Select the page background.

   You can control the background of the page and any controls that do not have a style sheet associated with them by specifying a style in the page background.

9. (Optional) Deselect Allow Deferred Processing if you want processing to occur each time the user presses the Tab key to advance through the page controls.

10. (Optional) Select Adjust Layout for Hidden Fields if you want the page borders to adjust automatically to accommodate fields that are hidden.

    Note. For the page to adjust automatically, the hidden fields must be surrounded by open space or have other hidden fields to the right or left.

11. (Optional) Select Disable Display in Modal Window When Not Launched by DoModal Peoplecode if you want the page to appear within the browser frame comparable to the standard application pages. If you select this option, you must use DoModal PeopleCode if you want the secondary page to appear as a modal page. Leave this check box deselected if you want the secondary page definition itself (not PeopleCode) to control the appearance.

    Note. This option is disabled when the page type is set to Popup page.

12. Click the OK button.

    The page definition size automatically adjusts if you set the page size to Auto-Size.

13. Save your secondary page.

Inserting Secondary Page Controls

After you define a secondary page, you can place a secondary page control on your primary page and associate it with the secondary page you just created.

To insert a secondary page control, access the primary page:

1. Select Insert, Secondary Page.

2. Click the primary page where you want to display the secondary page control.

   The secondary page control looks like a small push button with the secondary page icon on it. This control is invisible at runtime.

3. Double-click the control to access the Secondary Page Properties dialog box: Secondary Page tab.

4. Select the name of the secondary page to associate with the secondary page control on the active page.

   Only secondary pages can be associated with secondary page controls. You cannot associate a standard page or subpage with the secondary page control.

5. Select the Label tab.

   This label is for informational purposes only. It appears in the Order tab of the page definition and in the page description printout.

6. Position the secondary page control at the proper scroll level on the Order tab.

   See Specifying Type Properties for Push Buttons or Links.

7. Save the page definition.

Note. When you use secondary page controls on primary pages, you must also insert a push button control and write PeopleCode that invokes the secondary page.

See Also

Associating Secondary Pages With Primary Pages

Associating Secondary Pages With Primary Pages

You can use two page controls to associate a secondary page with a primary page:

• Insert a push button or link page control on the primary page.

  When you use this control type, you must set the Type properties to invoke the secondary page. At runtime, when the user clicks the push button or link, the secondary page appears. Use this control when:

  • You need no procedural PeopleCode logic before the secondary page appears (PeopleCode can be used on the secondary page just like any other page).

  • You want to control the formatting of the information (therefore, you want to use a page and not use the Prompt function).

  • You use the secondary page multiple times.

  See Using Push Buttons and Links.

• Insert a secondary page control on the primary page.

  This control looks like a command push button, but it is invisible at runtime. When you use a secondary page control, you must also insert and configure a push button on the primary page. After you set the push button Type properties to invoke Command PeopleCode, you then call the DoModal PeopleCode function from the FieldChange event for the push button to display the secondary page.

  See Inserting Secondary Page Controls.

  See Using Push Buttons and Links.

  See PeopleCode Built-in Functions.

Using HTML Areas

This section provides an overview of HTML area controls and discusses how to:

• Insert HTML areas.

• Populate HTML areas.

• Change HTML area labels.

Understanding HTML Area Controls

You can insert an HTML area control on any PeopleSoft page. You can insert it at any level on a page, and you can place it in a grid control. This control is rectangular and is easy to resize.

Populate the HTML area control in one of these ways:

• Statically, in the page field property sheet.

• Dynamically, by associating the control with a record field or HTML definition.

If the control is linked to a record field, the value of the record field appears in the HTML area. Use PeopleCode to associate the HTML area control with a predefined HTML definition.

When using HTML areas, consider:

• HTML areas are downloaded to Microsoft Excel as a nonbreaking space (&nbsp).

• HTML areas are not searched with the Find feature.

Generating Trees in HTML Areas

You can use the GenerateTree PeopleCode function with HTML areas. This example shows the tree that is created by the GenerateTree PeopleCode function on the Select New Parent Folder page:

Populating HTML Areas

You can populate an HTML area either statically, using the HTML Area Properties dialog box, or dynamically, by associating the control with a record field. Because the HTML that you write is included in the HTML that is dynamically generated by the system at runtime, consider the following:

• The HTML that you include can affect the page layout.

  Complying with the design-time sizing of the HTML area is the best way to ensure that you do not affect the layout of the other page field controls. Adding an invisible frame around the HTML area control can help ensure that you do not affect other page fields.

• You can use only certain types of HTML tags. These tags are not supported by the HTML area control:

  • <body>

  • <frame>

  • <frameset>

  • <form>

  • <head>

  • <html>

  • <meta>

  • <title>

Using JavaScript in HTML Areas

If an HTML area contains a reference to third-party JavaScript, you need to include the absolutized attribute in the script tag and set it to"false". For example:

<script type="text/javascript" language="javascript" ​absolutized="false"
   src="../../../../../ps/spellcheck/lf/spch.js">
</script>

Using Rich Text Editor-Generated HTML in an HTML Area

When you use the rich text editor (RTE) to generate HTML that appears in an HTML area page control, you must call the ProcessRTEHTML function to process the RTE-generated HTML before you assign it to the HTML area. The ProcessRTEHTML function wraps the HTML inside a <div> element, sets the style class to PT_RTE_DISPLAYONLY, and attaches the image processing JavaScript. Use the following code as an example:

Declare Function ProcessRTEHTML PeopleCode WEBLIB_PTRTE.ISCRIPT1 FieldFormula;

&HTMLAAREA.value = ProcessRTEHTML ("URL ID of the image target", "HTML Data To be⇒
 Processed");

Your code might look like this:

&HTMLAAREA.value = ProcessRTEHTML (URL.PT_RTE_IMG_DB_LOC, "<p>example</p>");

The &HTMLAAREA.value should be similar to this:

<div id="RTEDiv188" class="PT_RTE_DISPLAYONLY">
  <p>example</p>
     <script type="text/javascript" language="JavaScript">
          PTRTE_CheckImages("", "PT_RTE_IMG_DB_LOC", "RTEDiv188");
     </script>
</div>

Using HTML Areas in AJAX Mode

Note the following code restrictions in HTML areas when running the application in AJAX mode:

• Do not include XML tags, such as CDATA.

• Do not include empty or commented out <script> elements.

• Do not include document.write as part of the HTML in an HTML area.

See Also

Using the GenerateTree Function

Inserting HTML Areas

To insert an HTML area on a page:

1. Select Insert, HTML Area.

2. Draw the HTML area on your page.

3. Move the HTML area control by dragging it with the mouse or by pressing the arrow keys.

Populating HTML Areas

This section discusses how to:

• Populate an HTML area statically.

• Populate an HTML area dynamically.

Populating an HTML Area Statically

Use the HTML Area Properties dialog box to populate an HTML area:

To populate an HTML area statically:

1. Access the HTML Area Properties dialog box.

2. On the HTML tab, select Constant as the value type.

3. In the long edit box, enter the HTML code that you want to appear in the HTML area.

Populating an HTML Area Dynamically

To populate an HTML area dynamically:

1. Access the HTML Area Properties dialog box.

2. On the HTML tab, select Field as the value type.

3. Specify the record and field to which you want to associate the HTML area control.

   The value of the record field generates the HTML code that is included at runtime in the HTML area.

   Note. When you associate an HTML area control with a field, make sure that the field is long enough to contain the data that you want to pass to it. For example, if you associate an HTML area control with a field that is only 10 characters long, only the first 10 characters of your text will appear. You should use long character fields for record fields that are associated with an HTML area control.

Changing HTML Area Labels

Assign a distinct label to your HTML area to distinguish it from other HTML area controls on the Order tab of the page.

To change an HTML area label:

1. Access the HTML Area Properties dialog box.

2. Select the Label tab.

3. Enter a brief text description of the HTML area.

   This label does not display at runtime; however, it appears on the Order tab of the page definition.

Using Push Buttons and Links

This section provides an overview of push buttons and links and discusses how to:

• Insert push buttons or links.

• Specify type properties for push buttons or links.

• Specify label properties for push buttons or links.

• Specify use properties for push button or link.

• Programmatically change hover text for push buttons or links.

Understanding Push Buttons and Links

PeopleSoft Pure Internet Architecture supports these features for push button and link controls:

• Selecting link style.

• Selecting these types of push buttons and links:

  • External link.

  • Instant messaging action.

  • Internal link.

  • Page anchor.

  • PeopleCode command.

  • Process.

  • Prompt action.

  • Scroll action.

  • Secondary page.

  • Toolbar action.

• Selecting these image options:

  • On mouse over.

  • When disabled.

Inserting Push Buttons or Links

After you add a push button or link control to your page, you can define the attributes by opening the Push Button/Hyperlink Properties dialog box.

To insert a push button or link:

1. Select Insert, Push Button/Hyperlink.

2. Click where you want the upper, left-hand corner of the control to begin.

   A push button of small image size appears.

3. Double-click the push button to access the Push Button/Hyperlink Properties dialog box.

4. On the Type tab, select whether the control appears as a push button or link.

5. Select a destination type from the Destination drop-down list box.

   See Specifying Type Properties for Push Buttons or Links.

6. Select the record and field names with which you want to associate the push button or link.

7. Select any of the remaining Type options based on your destination type.

8. On the Use tab, select the purpose of the control.

   See Specifying Use Properties for Push Buttons or Links.

9. Save the page.

Specifying Type Properties for Push Buttons or Links

Access the Push Button/Hyperlink Properties dialog box.

Type Tab

Each destination type that you select enables a different region on the Type tab, enabling you to further define your push button or link. Select one of these values from the Destination drop-down list box:

External Link Group Box

In this group box, select Dynamic or Static and enter the URL ID, if necessary. Select a value from the URL Maintenance table of a record field to define the destination. For example, a derived record field might be used to set the destination value dynamically at runtime. The value of the derived record field is placed in the <HREF> tag of the HTML.

See URL Maintenance.

Internal Link

Specifying Label Properties for Push Buttons or Links

This section discusses how to:

• Specify a text label.

• Specify an image label.

Specifying a Text Label

To specify a text label for a push button or link:

1. Access the Push Button/Hyperlink Properties dialog box.

2. Select the Label tab.

3. In the Type group box, select Text.

4. Select the size.

   Standard push buttons can be one of three sizes, depending on what kind of text or image you want to display on the button face.

   Small Image	Creates toolbar-sized buttons that handles small 16 × 16 pixel images.
   Large Image	Handles 32 × 32 pixel images.
   Standard Text	Matches the Microsoft standard dimensions for text push buttons.
   Custom	Select if none of these sizes meets your needs. When you click OK, the push button displays selection handles that you can use to resize it.

5. Specify the type of label text.

   Depending on the destination type that you selected, the values in the Type drop-down list box differ.

   Message Catalog	Select to reference a message that exists in the message catalog. Enter the message set and number. Message catalog items are all translatable.
   RFT Short (record field table short)	Select to label the push button with the short name for the field from a record definition. The RFT stores attributes for fields in a record definition. Use this option only if you specified a record definition and field name on the Type tab in the Push Button/Hyperlink Properties dialog box. The RFT short name appears on the push button when you click OK and return to the page. Select the label ID if you do not want to use the default label if more than one label has been set for the record field.
   RFT Long (record field table long)	Select to label the push button with the long name for the field. Use this option only if you specified a record definition and field name on the Type tab in the Push Button/Hyperlink Properties dialog box. The RFT long name appears on the push button when you click OK and return to the page. Select a different label ID if you do not want the default label if more than one label has been set for the record field. The system uses the RFT long label as the tool tip at runtime for links if it is different from the assigned display value of the link and it is not null. If more than one label is stored for the record field, you can select an alternate tool tip from the Label ID drop-down list box.
   Static Text	Select to enter the text to appear on the label.
   URL Description	Select if you selected External Link as the destination on the Type tab. Select the style from the drop-down list box. See Creating Style Sheet Definitions.

6. Select the alignment.

   This option is only available if you selected Hyperlink for the type on the Type tab. Push button text is automatically centered for controls that appear as push buttons. Push buttons with text and images are automatically center-aligned when used in grids.

Note. Some browsers do not support customized push buttons.

See Troubleshooting Browser Limitations available on the My Oracle Support website. support.oracle.com

Specifying an Image Label

To specify an image label for your push button or link:

1. Access the Push Button/Hyperlink Properties dialog box.

2. Select the Label tab.

3. Select Image for the type.

4. Specify the size.

   If you select Custom, the Image/Format Size group box becomes available.

   Scale	Select to adjust the width and height as percentages.
   Size	Select to set the image size by altering the width and height in pixels.
   Reset to actual image size	Resizes the image according to its natural size. That is, the image size is not manipulated by custom width or height values.

5. Specify the image ID.

   Select one of the predefined image definitions or click the Browse button to view push button images.

   See Understanding Image Definitions.

6. In the Alt tag for image group box, specify the hover text type.

   Message Catalog	Select to reference a message that exists in the message catalog. Enter the message set and number. Message catalog items are all translatable.
   RFT Long (record field table long)	Select to use the long name of the record field as the hover text. Use this option only if you specified a record definition and field name on the Type tab in the Push Button/Hyperlink Properties dialog box. The system uses the RFT long label as the tool tip at runtime for links if it is different from the assigned display value of the link and it is not null. If more than one label is stored for the record field, you can select alternate hover text from the Label ID drop-down list box.
   RFT Short (record field table short)	Select to use the short name of the field as the hover text. Use this option only if you specified a record definition and field name on the Type tab in the Push Button/Hyperlink Properties dialog box. If more than one label is stored for the record field, you can select alternate hover text from the Label ID drop-down list box.
   Static Text	Select to enter the text that will appear on the label.

7. (Optional) Select the image that will appear on a mouse over.

   For example, you might want to highlight an image so that users can easily see which option they are selecting.

8. (Optional) Select an image that will appear when the button is disabled.

Specifying Use Properties for Push Buttons or Links

Access the Push Button/Hyperlink Properties dialog box and click the Use tab.

Field Use Options

This table describes the Field Use options:

Grid Cell Alignment

Push buttons with images or text are center-aligned automatically when in a grid. Otherwise, select Left, Centered, or Right.

Note. Grid cell alignment properties are only enabled when the control is contained within a grid and the control type is configured as a text hyperlink.

Mouse Over Popup

Select the Display Only check box to enable the Mouse Over Popup options. Select from these mouse over pop-up options:

Note. Attempts to make a push button/hyperlink editable at runtime when it has a mouse over pop-up page associated with it, for example, using PeopleCode, will fail.

See Also

Understanding Pop-up Pages

Programmatically Change Hover Text for Push Buttons or Links

Hover text or mouse over text enables you to display additional or supplemental information about a button or link. Under certain circumstances, you might want to vary the hover text based on the context of application data on the page.

You can alter hover text by using the PeopleCode HoverText Field property. This property sets the hover text for any buttons or links associated with the field. The maximum length of hover text is 100 characters. You can use the Message Catalog to store hover text.

Example: Changing Hover Text Programmatically

To set hover text for a push button or link at runtime, use PeopleCode to define the HoverText property for a field definition.

QE_ABSENCE_HIST.QE_ABSENCE_TYPE.HoverText = MsgGetText(95, 5037, "Personalize Layout");

Note. The HoverText Field class property is available for the push button/hyperlink page control only.