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.

  • Include HTML areas in the page tab order.

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:

Image: Example of a tree in an HTML area

This example illustrates the fields and controls on the Example of a tree in an HTML area. You can find definitions for the fields and controls later on this page.

Example of a tree in an HTML area

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

When using an HTML area field for adding JavaScript, make sure that JavaScript code is added only once per page. It should not be added in multiple places on a single page unnecessarily. This improves browser performance, especially for display on mobile devices.

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.

Using HTML Areas in Grids or Scroll Areas

If HTML area fields are used in a grid or in a scroll area, they can cause performance degradation if there are more than 50 rows in the grid or in the scroll area, or if there are many HTML area fields in the grid or in the scroll area. This is due to the behavior of partial page refresh. During a partial page refresh, the system cannot determine what has been changed within the fields of an HTML area, so all fields in an HTML area are refreshed, regardless, which can hamper performance.

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.

This section discusses how to:

  • Populate an HTML area statically.

  • Populate an HTML area dynamically.

Image: HTML Area Properties dialog box - HTML tab

This example illustrates the HTML tab of the HTML Area Properties dialog box. The Constant radio button has been selected, which determines that static HTML code can be entered in the edit box.

HTML Area Properties dialog box - HTML tab

Field or Control

Definition
Field

Select the Field radio button to enable selection of a record field for populating the HTML area dynamically at run time.
Constant

Select the Constant radio button to enable entering static HTML code in the text entry area below.
HTML Tags Only

Select this check box to disable processing of the HTML code that will relocate special tags such as <meta> and <script> from the body of the code into the <head> section of the HTML document. Therefore, this check box should be selected only when the HTML code includes tags that are for the <body> section of the HTML document.
Record Name

When the Field radio button is selected, select the record name.
Field Name

When the Field radio button is selected, select the field name that contains the HTML code at runtime.
Respond Once Only

Select this check box to indicate that this HTML area is to be included in the AJAX response one time only, except when some other properties of the HTML area have been changed, such as its content, label, and so on. When this check box is unselected, the HTML area is always included in the AJAX response. This setting applies to HTML areas at any level (from level 0 to level 3).

Note: This setting can be overridden by the ForceUpdateOnce property of the Field class.

Populating an HTML Area Statically

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 text entry area, 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.

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

Note: Unlike other page controls, the label for an HTML area is displayed on the Order tab only and is not displayed at runtime when the page is rendered in the browser.

Image: HTML Area Properties dialog box - Label tab

This example illustrates the Label tab of the HTML Area Properties dialog box.

HTML Area Properties dialog box - Label tab

Field or Control

Definition
Type

Select the label type:

  • None — Select to display no label on the Order tab.

  • Text — Select to display text that you enter in the Text field. The default text is the long name for the field from the associated record definition.

  • Message Catalog — Select to display a Message Catalog entry as the label.

  • RFT Long — Select to display the RFT long name for the field from the associated record definition. This value is the default.

  • RFT Short — Select to display the RFT short name for the field from the associated record definition.
Text

Enter the text to display on the Order tab.
Label ID

Select from the drop-down list box the label you want to use for the HTML area. The available choices are based on the Label ID column and the Long Name column for the selected field definition.

The default setting for this option is Use Default Label. This default is determined by the label you select as the default for the field definition.
Context

Displays text to assist the translation team determine the context of the field label to be translated. The context is determined by the field name and label ID combination. If no contextual information exists in the database, then no text appears in this field.
Message Set/Msg Number

Enter the message set number and message number to specify the label text.

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.

When the PeopleSoft system generates HTML for a page, it creates a tab index, or order, including every control or widget on the page, based on the field order for that page in Application Designer. However, with HTML areas, the system skips any control defined within an HTML area, by default, when building the tab index. In some situations, this may be confusing to an end user, such as in the case when screen readers are used.

To include the controls in an HTML area within the page tabbing order, add the %tabindex meta-variable to the HTML. At runtime, for each field inside an HTML area that is defined with the %tabindex meta-variable, %tabindex will be replaced with the tab index of the HTML area itself.

In the following example, two fields have been defined with the %tabindex meta-HTML variable, while one has not:

<a href="http://www.w3schools.com" tabindex="%tabindex">Visit W3Schools.com!</a>
<a id="HELP" name="HELP" href="javascript:some_function1();" tabindex="%tabindex">Help</a>
<a id="NEWWIN" name="NEWWIN" href="javascript:some_function2();">New Window</a>

At runtime, if the tab index for the HTML area is 20, then this HTML fragment resolves to:

<a href="http://www.w3schools.com" tabindex="20">Visit W3Schools.com!</a>
<a id="HELP" name="HELP" href="javascript:some_function1();" tabindex="20">Help</a>
<a id="NEWWIN" name="NEWWIN" href="javascript:some_function2();">New Window</a>

This metavariable is documented in more detail in the PeopleCode documentation, see %tabindex for more information.

Note: The tab order of controls within an HTML area cannot be customized by end users.