Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

Control form - Completing the HTML tab

Updated on November 15, 2021
Applicable to Theme UI-Kit applications

For non-auto-generated controls, you can enter HTML source directly into the HTML Source text box.

FieldDescription
Omit extra spacesSelect 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. 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 whitespaces. 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 (&NBSP;) into the processed HTML without change.
Property typeOptional. If this control is a likely choice for presenting a field on a user form or flow action form, you can select a type or ALL in this field.

Your choice helps a developer - while working on a harness, section, or flow action - select an alternate HTML format for a property that is best suited to the application need. This value acts only as a filter; it does not prevent this control from being referenced by any property. (The Double type is not an option for this field.)

If not blank, the name and two previews (read-write mode and read-only) of this control appear on the pop-up list accessed by the View properties icon on the Cell Properties panel, for Harness and Section forms (in the SmartFrames format). For example, if the property type is DateTime, see Adding a Date time control to a layout.

Note: This field is intentionally blank on a few standard controls including Autocomplete, ListToList, and Chart that are never intended to be associated with a single property on the Property form. These special controls support advanced features available from the Layout tabs of the Harness and Section form and the Format tab of the Flow Action form.
Display Optional. If this control is a likely choice for presenting a field on a user form or flow action form, you can select a format here. Your choice helps a developer - while working on a harness, section, or flow action - select an alternate HTML format for a property that is best suited to the application need. This acts only as a filter; it does not prevent this control from being referenced by any property:
  • Select Input if the field is likely to be presented by an HTML element <INPUT TYPE = "INPUT" ...>
  • Similarly, select Select if the field can be represented by an HTML selection list, corresponding to the element <HTML INPUT TYPE="SELECT" ...>
  • Select Radio or Text Area if the corresponding HTML elements are likely to apply.

If not blank, the name of this control appears on the pop-up lists on the Field panel, for Harness and Section forms (in the SmartFrames format only).

Note:

INPUT element

When you use an INPUT element for a text box, check box, selection box or text area in the HTML text of a control, use this JSP syntax:

<INPUT name=""<pega:reference name=""$this-name"" />""

When using directives, you can omit the NAME attribute and its value. The system determines the NAME and value from the property that references your control.

Auto-generatedWhen selected, HTML text for the control is generated based on settings in the Control tab. Standard auto-generated rules have this check box selected by default. If you deselect this check box, the system conceals the Control tab and displays the Parameters tab.
Note: Do not deselect this check box in auto-generated rule forms. Doing so disables access to the Parameters dialog from the Control Cell properties panel in a section or harness.

As a best practice, create new controls as auto-generated, and deselect this check box. When developing non-auto-generated controls, avoid hand-edited HTML when other approaches can achieve the same result. When you do incorporate hand-edited HTML, JavaScript or CSS, use the Rule Security Analyzer to detect potential security vulnerabilities.

Generate for 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 controls, the initial value is JSP.
Note: Use of JSP tags in controls offers superior performance and other advantages over directives. Although both directives and JSP tags are supported, JSP tags are recommended for new development.

Controls that accept parameters must use JSP tags.

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.

Browser supportIndicate which browsers and versions can display the JSP or HTML from this rule. The Pega Platform does not validate your code. You must ensure that your code can be displayed in supported browsers. The value is read-only.
AccessibilitySelect 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.

Show in authoring menusSelect to include the control in the palettes available in the section.
Select paletteSelect the palette in which you want your custom control to appear, either Basic or Advanced.
Control imageAdd an icon to display in the palette next to your custom control.
HTML Source For non-auto-generated controls only. Enter the HTML, JavaScript, and CSS code. The text can include JSP tags or directives, but not both.

If this control is to support parameters entered on the Parameters tab, use only JSP tags and set the Generate for field to JSP.

Note:
  • JavaServer Page tags

    Use of JSP tags in controls offers superior performance and other advantages over directives. Although both directives and JSP tags are supported, JSP tags are recommended for new development. Conversion of existing control that use directives to functionally equivalent rules that use JSP tags is straightforward.
  • Inline Java and access to parameter values

    Use the <% and %> delimiters to insert inline Java code (a scriptlet) in the HTML. Within the code, use Java syntax similar to the following to obtain the runtime value of a parameter from the parameter page, where MyType is defined on the Parameters tab:

    <%
    String MyTypeParam = tools.getParamValue("MyType")
    ...
    %> 

    For additional examples, review the Java code in the standard control named Decimal.

  • Including JavaScript function definitions

    See More about Controls.

Tips

Use the <pega:when > JSP tag to conditionalize the HTML for a property based on the mode (display or read-only mode versus read-write mode).

To detect review mode, use:

<pega:when test="!$mode-input">
   <!-- display stuff here -->
</pega:when >

Useful JSP tags

These tags are used often. Don't forget to include the closing elements.

JSP tagResult
<pega:when test="!$mode-input"> ...
</pega:when>
Read-only mode.
<pega:when test="$this:isBad">
...
</pega:when>
Error on this element.
<pega:reference
    name="$this-value" />
Value of the active property.

Example

This example causes the output HTML to display a read-only value if the property value appears in read-only mode, or a select box with three choices if the property appears in read-write mode.

<pega:when test="$mode-display" >
   <pega:reference name="$this-value" />
</pega:when>
<pega:when test="mode-input" >
<SELECT >
   <OPTION VALUE="Best">Best</OPTION>
   ;<OPTION VALUE="Replaced">Replaced</OPTION>
   <OPTION VALUE="Obsolete">Obsolete</OPTION>
</SELECT>
</pega:when >
  • Using the Accessibility report

    Use the Accessibility report to assess your application's level of accessibility compliance. The report uses a chart to illustrate accessibility compliance by rule type and percent (%) of accessibility. You can drill down in the chart to display additional levels of detail about individual accessible elements within the rules.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us