You are here: User interface > User interface rules > Harness, Section, and Flow Action forms > Adding a Data Field

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

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 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

Click the gear icon to display the Cell Properties panel.

General tab

Field

Description

(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

Select or type a property reference that identifies a single text value.

Label Check the check box 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

Optional. 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 the gear icon to start the Expression Builder.

Choose 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 check box, if it appears, to have a blank area appear in the section when the paragraph is hidden.

Do 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, as a best practice, click the gear icon and create the expression by using the Expression Builder. 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. Click the Open icon to review or create the rule.

Required

Select the Required check box to make this a required field.

This option is available only for fields in cells on flow actions and sections. Select to require that when the form appears at run time in read-write mode, users cannot successfully submit the form if the field is blank.

Selecting Required marks the label for this field with an orange asterisk 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 run time, 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.

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 Presentation Options

Instead of creating a new custom format in the skin, you can adjust elements in a cell by applying Cascading Style Sheet (CSS) helper classes. For example, you can use a CSS helper class to center an element in a cell or to double the standard right margin for the element.

  • Cell read-write classes – Click the Open helper class picker icon to specify one or more CSS helper classes to apply to this cell when the form is displayed in read-write mode. You can enter several helper classes, separated by a space. Alternatively, you can enter the name of a custom style to apply to this cell.

  • Cell read-only classes – Click the Open helper class picker icon to specify one or more CSS helper classes to apply to this cell when the form is displayed in read-only mode. You can enter several helper classes, separated by a space. Alternatively, you can enter the name of a custom style to apply to this cell.

  • Inline style (not for production use) – You can use this field to define an inline style by entering CSS code. However, entering an inline style results in a guardrail warning. For maintainability and reuse, the recommended approach is to use read-write or read-only classes.

For more information, see CSS helper classes.

Actions tab

See Actions.

About Flow Actions

About Harnesses

About Sections