Control form - Completing the HTML tab

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

Field	Description
Omit extra spaces	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. 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 type	Optional. 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-generated	When 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 support	Indicate 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.
Accessibility	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.
Show in authoring menus	Select to include the control in the palettes available in the section.
Select palette	Select the palette in which you want your custom control to appear, either Basic or Advanced.
Control image	Add 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 tag	Result
`<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 >