Back Forward Harness and Section forms
Fields — Adding a Data Field for a composite application

 About Harnesses

When you build a Pega composite application with Internet Application Composer, you embed the application on an external Web page as a gadget in a <DIV > element. A Data Field is an invisible field that makes the value of a scalar, single-value property from the composite application available to the external page. For example, say you want to display the operator's organization in a heading at the top of the external Web page. In such a case you add a Data Field for .pyOrganization to the harness or one of the sections or flow actions.

The external page hosting a composite application can access only those properties that are represented by a Data Field control somewhere in the harness displayed by the <DIV >. The values of these properties are read-only.

1. Drag and drop the Data Field control

Click the down-arrow Arrow at the right end of the Advanced control group and select the Data Field control. Drag the control to the cell or header that is to contain the property value. When the pointer changes shape to indicate that a single cell is selected, release the mouse button to drop the control.

If you drop the control into a cell that already has contents, it replaces the current contents of the cell.

2. Complete the Cell properties panel — Top fields

ClickMagnifying glassicon to display the Cell Properties panel.

General tab

Field

Description
magnifying glass

(Appears only when this field is in a section included within the current open rule.) Click to open the section that immediately contains the field.
Property

SmartPromptSelect or type a property reference that identifies a single text value.
Label Check the checkbox to use the default label for the property; or uncheck it and, in the field that appears, select or create a label.
Label format Select a format from the available options.
Default value

SmartPromptOptional. Enter a constant value for the property value, a property reference, or an expression, to be used only when the user form or flow action form appears in read-write mode rather than read-only mode.

Click magnifying glass to start the Expression Builder.

NoteChoose a default value that speeds data entry. When the system renders a harness or section in read-only mode (for example because the read-write mode requires a privilege that the current user does not hold), the default value does not appear, because data entry is not permitted.

Visibility Select to determine when the property value is to appear. Always is the default. (If this setting is not applicable, the cell contents are blank.)
  • Choose Always, If Not Blank, or If Not Zero to have the field appear or be hidden based on the property value at the time this area of the user form (section or flow action) is first presented or refreshed. This condition is checked only once.
  • Choose Other Condition to make the visibility depend on a when condition rule or a Java expression.

Check the Reserve space when hidden checkbox, if it appears, to have a blank area appear in the section when the paragraph is hidden.

CautionDo not make an input field invisible if your application expects user input on the field. When a user submits an HTML form, an input field that is not visible is not included in the HTTP details.

Disable

Select one of the available options:

  • Never: the control is always enabled.
  • Always: the control is never enabled
  • Condition (expression): In the field that appears you can provide a simple expression based on the comparison of a pair of constants, properties, or both, combined by Boolean operators, such as .Color="Red". You can combine the expression with a when condition or another expression using the && and || operators. However, Pega recommends you click the gear icon and create the expression using the Expression Builder form that appears. See Using the Condition Builder to configure dynamic UI actions.
  • Condition (when rule): In the field that appears provide the When Name key part of a when condition. Clickmagnifying glass to review or create the rule.

 
Required Appears only for fields in cells on flow actions and sections. Select to require that when the form appears at runtime in read-write mode, users cannot successfully submit the form if the field is blank.
NoteSelecting Required marks the label for this field with an orange asterisk REQUIRED when the flow action form appears in read-write mode. (The asterisk also appears if the Label control's Value For field is not blank and the Label control's Required box is checked.)
For sections, checking this box enables client-side format validation when this section is part of a harness form that has the Enable Client Side Validation box selected on the HTML tab. At runtime, users who leave this field blank and submit the form are notified immediately that the field is required; the form is not transmitted to the server.

Check the Required checkbox to make this a required field.

Presentation tab

Field

Description
Edit Options Select an edit mode for this control. The edit mode of the control, specified here, takes precedence over section and harness settings.
  • Auto — the control uses the edit mode of the section or harness in which it appears. If the section is set to Read Only, then the control is Read Only. If the section is set to Auto, then the control uses the edit mode of the harness. For example, a New harness is editable, while a Review harness is read only.
  • Editable — the control is editable, regardless of the edit mode of the enclosing layout.
  • Read Only — the property value is presented in read-only mode always, or based on a when condition rule or client-side test, even when the enclosing layout is in read-write mode.
Advanced Options

Appears only when you select the Display advanced presentation options checkbox.

NoteThe best practice is to define custom styles in the skin.

  • Cell read-write style — Type the name of the custom style, for example, custom_stylename, that you want to apply to this cell when the user form or flow action form appears in read-write mode.
  • Cell read-only style — Type the name of the custom style, for example, custom_stylename, that you want to apply to this cell when the user form or flow action form appears in read-only mode.
  • Cell inline style — Type CSS code to define an inline style. As a best practice, define custom styles in the skin. See Skin form — Components tab — General — Custom styles.

Parameters tab

There are no parameters to set.

Actions tab

See Actions.

Up About Flow Actions

Up About Harnesses

Up About Sections