Section form
Completing the HTML tab

Description

Select in most cases to allow the Pega Platform to generate HTML text for the section based on information in the Design tab.

Note: Hand-edited HTML in sections can introduce complex, difficult-to-debug processing into your application. Clear this check box only when necessary. Following the guardrails, avoid hand-edited HTML in sections when other approaches can achieve the same result. As a best practice, use the Rule Security Analyzer to detect and correct for security vulnerabilities.

Caution: If this rule is later saved with the Auto-Generated HTML box selected, your HTML changes are overwritten.

Select to generate portlet-compliant HTML that can be displayed by a portal server. Portlet-compliant HTML meets the requirements of Java Specification Request 168, which defines the portlet standard.

This box is available only when the Auto-Generated HTML box is selected.

A portlet-compliant section form can be sent to an external portal server through Service Portlet rules and displayed in a portlet window.

Select to indicate that at runtime, user presentation of this section is to be localized based on field value rules in a language-specific ruleset text elements.

This check box is available only when Auto-Generated HTML is selected and Generate for is set to JSP.

For each locale, you must add field value rules in such a ruleset to support presentation of this section. Typically, use the Localization wizard and the Rules Inspector tool to identify, create, and maintain these field value rules. See:

• Internationalization and localization — Concepts and terms
  
• About the Localization wizard 
• Localizing forms and reports with the Field Value Inspector 

Note: When selected, the generated HTML calls the PublicAPI Java function getLocalizedTextForString() at runtime to convert text in the pyCaption, pyButtonLabel, pyActionLabel, pyActionPrompt and other properties to a locale-specific value.

Select to eliminate extra space characters in the processed HTML. This can make transmission or processing more efficient. It does not alter the appearance of the HTML when displayed in a browser.

When selected, the way the system handles stream processing is different for JavaServer Pages (JSP) streams and HTML streams.

JSP streams replace consecutive spaces and control characters with a single space. For example: << space >><< new line >><<tab>> is converted to << space >>. Two or more consecutive space characters are replaced with a single space, except within the curly brace characters defining directives.

As a best practice, remove all line breaks and whitespace. For example:

<pega:choose>

   <pega:otherwise>

Some Value

</pega:otherwise>

</pega:choose>

becomes:

<pega:choose><pega:otherwise>Some Value</pega:otherwise></pega:choose>

HTML streams delete control characters appearing at the beginning of the rule definition and immediately after a directive, but otherwise behave like JSP streams. For example:

<< tab >>{some directive}<< tab >><< space >><< tab >>{some directive}<< space >><< space >>

is converted to:

{some directive}<< space >>{some directive}<< space >>

HTML stream processing copies space characters within the text of a property value and non-breaking spaces ( ) into the processed HTML without change.

Select to use this section as a custom user interface component built with third-party JavaScript libraries such as JQuery, Adobe Flash/Flex, or FusionCharts. You can include this section as a layout or inside a cell. This section cannot be autogenerated; the Auto-generated HTML, Portlet compliant and Localize fields are disabled. The Generate for, Browser Support, and Accessibility options are available.

Enter your code using HTML, CSS, JS, Flash, Flex, and so on in the HTML Source area.

When you select this option, the Parameters tab displays an array for entering the names and descriptions of Single Value, Page Value, or Page List parameters that you want to pass to this section. You can enter literal values in the array and retrieve them as regular parameters using unique specialty component IDs and API functions to:

• Set data to the clipboard before submitting the page.
• Get clipboard data when loading a page.

This feature requires advanced JavaScript skills. See Notes: in the HTML Source area for details.

Typically, the system sets this field to HTML or JSP, to indicate whether the HTML source is to contain HTML directives or JSP tags. For new sections, the initial value is JSP.

Use of JSP tags in sections offers superior performance and other advantages over directives. Although both directives and JSP tags are supported, JSP tags are recommended for new development.

If the Auto-generated HTML box is not selected, use only JSP tags or directives — not both — in the custom HTML you add to this rule. Set this field to reflect your choice.

Notes:

• If this rule is circumstance-qualified or time-qualified, make this Generate For value match the Generate For value of the base rule. The base rule and the qualified rules must all use JSP tags or all use directives.
• Do not save the rule form if you have composed HTML that contains both JSP tags and directives.
• The setting on this rule may differ in other sections referenced in this section. For example, a section that uses JSP tags may include a section that uses directives.

This field indicates which browsers and versions can correctly process the HTML code from this rule.

If the Auto-generated HTML option is selected, the value is All Supported Browsers and is read-only. The Pega Platform includes only those tags and features that can be displayed in supported browsers, which include Internet Explorer, Firefox, Safari for Windows, and Chrome. For the exact list of supported browsers and versions, consult the Platform Support Guide on the PDN.

If the Auto-generated HTML option is not selected, and you edit the generated code or manually provide the code for the rule, select All Supported Browsers or IE only. When you do not use auto-generated code, the Pega Platform does not validate your HTML code. You must verify that it can be displayed by the browsers you specify.

This field is available when Auto-Generated HTML is not selected.

Select On to indicate that you have designed and implemented your HTML to meet your accessibility requirements.

The Accessibility Report evaluates this field on each rule in an application that displays it, when calculating application accessibility compliance levels. See Using the Accessibility report.

At runtime, the Pega Platform uses stream processing to evaluate the JSP tags or directives in this source HTML (which reference properties and other rules such as HTML fragment rules, HTML rules, controls and sections) in the context of current clipboard contents and static files.

The Pega Platform then sends the resulting HTML to the HTTP server, which transmits it and the associated static files (images, scripts, and style sheets) to the Internet Explorer browser on the client workstation.

To edit the generated source:

1. Save the rule form once with the Auto-generated HTML check box selected.
2. Clear the Auto-generated HTML check box.
3. In the HTML editor, override generated HTML code with custom code.
4. Exit from the HTML editor and save the rule form again.

When you select Specialty Component, the system populates this area with a template containing sample JavaScript that is required for integrating this component with a harness.