Back Forward Harness, Section, and Flow Action forms
Adding a Text Area control

About Harness rules

  Show all 

A cell in a layout can present the value of a property, as display-only or as an input field. Follow these instructions to control the presentation of a property value in a Text Area control.

As of V6.1 SP2, the Text Area control uses the auto-generated control rule pxTextArea. Its look and behavior are governed by the rule form's Control tab. The Parameters tab is not available and the HTML cannot be edited. To modify the control's look or behavior, use the control's Parameters dialog within the context of the section, not the rule itself.

It is recommended that you use pxTextArea in new development rather than the non-auto-generated rule TextArea (which is supported). See About the TextArea control rule.

  1. Drag and drop the Text Area control

Click the down-arrow (Arrow) at the right end of the Basic control group (Basics) and select the Text Area 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 the cell is not empty, the dropped control replaces the current contents of the cell

  2. Complete the Cell Properties panel — Top fields

Click the magnifying glass icon (Magnifying glass) to open the Cell Properties panel. Complete the top fields that appear.

If the panel is pinned (Pinned), the wireframe presentation on the rule form changes immediately to reflect of your inputs. If the panel is not pinned (not pinned), click Apply to apply your inputs. GRP-229

Field

Description

Pencil 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 SmartPrompt Select or type a property reference that identifies a single text value.

Alternatively, you can drag a property name from the lists of properties visible in the Application Explorer. Typically, this works for Single Value properties belonging to in the Applies to class of the current rule (or a higher class). If the container in which this field sits has a non-blank Using Page value, you can drag a Single Value property from within that embedded page property.

Click the pencil icon (Pencil) to review the property rule (if the reference is to an existing property in the Applies To class of this rule or a parent of that class). If the property is not found, the New dialog box for the property form appears.

You can reference properties on any page identified on the Pages & Classes tab, using the normal notation pagename.propertyname for pages other than the page corresponding to the Applies To class of the rule.

If this field is in a cell of a section that includes parameter declarations on the Parameters tab, you can enter the notation param.NAME here, to use a parameter value for the field, where NAME identifies a string parameter. Make sure that the NAME parameter is declared on the Parameters tab, and that your application provides a non-blank value for the parameter value in all possible situations where the section appears. See Section rules — Completing the Parameter tab.

Control Accept the default pxTextArea control rule. When placed in a SmartLayout field, the adjoining Label cell is populated by the standard .pyTemplateTextArea property with a value of Text Area. When placed in a repeating grid, the value appears above the control in the header cell.

Click the pencil icon (Pencil) to review the control rule identified in this field.

Customizing the control

The control's default parameters are the ones you'll most likely use in your UI design for both edit and read-only modes. If you wish, you can customize the control within the context of the section that contains it. For example, you can:

  • Specify the text area's width it in pixels or as a percentage rather than let the size of the cell determine the width.
  • Specify the width and height of columns and rows.
  • Add settings based on the property type used with the control. For example, for a read-only Number format , you can specify a negative format, scale, and decimal places.

Your edits apply only to the control within the section that contains it and do not update the underlying rule. You an add multiple controls of the same type within a section, each with its own custom settings. See Control Form — Completing the Control tab for descriptions of the available parameters and how to define behaviors.

Do the following to customize an auto-generated control rule in a section:

  1. Open the section or harness that contains the rule.
  2. Select the cell containing the rule and open its Cell Properties panel.
  3. In the panel, select the magnifying glass icon () next to the Control field. This displays the control Parameters dialog, which contains most of the settings in the underlying rule's Control tab. You cannot edit the Control Modes and UI Element settings.
  4. Modify as necessary. To immediately render your changes, click OK in the dialog. If satisfactory, save the section. The system generates the XML representing your edits and stores it in the section.
Behavior Optional. Leave blank if no dynamic form actions to other parts of the form are to occur based on user updates or values for this field. C-1990

To establish a dynamic form action, click the magnifying glass icon (Magnifying glass) to open the Client Event Editor in a new dialog window. Complete the Client Event Editor to select an event (On Blur, On Change, or On Click) and the resulting form action. C-2526

Click the help icon ( Help) on the Client Event Editor for assistance. For general information on this capability, see Implementing dynamic form actions and the Client Event Editor.

Client event support is not available for harness, section, or flow action rules that use directives.

  3. Complete the Cell Properties panel — General tab

Complete the General tab.

Field

Description

Visible: Select to determine when the property value is to appear. (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 work object 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, a Boolean expression evaluated only once, or a test evaluated repeatedly upon JavaScript events. C-1990 B-21692

CautionWhen a user submits an HTML form, an input field that is not visible is not included in the HTTP details. Don't make an input field invisible if your application expects user input on the field. MARTT 2/28/07

Condition

SmartPrompt If you selected Other Condition for the Visible field, complete this field. Enter an expression involving another property, or identify the When Name key part of a when condition rule. PROJ-283 Specify one of three outcomes:

  • When condition rule — Enter the When Name key part of a when condition rule that determines the visibility of this field at runtime. The system uses the Applies To key part of the current rule in rule resolution to locate the when condition rule. Click the pencil icon (Pencil) to review or create the when condition rule.
  • Expression evaluated once — Enter an expression that returns true or false. This expression can involve multiple properties, function calls, and other syntax as supported by the <pega:when > JSP tag.
  • Simple Java expression evaluated upon JavaScript events — To dynamically control the visibility of this property with a JavaScript event, enter one or more comparisons involving a target property values to literal constant values and select the Run on Client? box. You can use parentheses and the && and || operators to group comparisons. At runtime, the result determines whether the content of this cell appears in read-only mode or in the mode of the enclosing layout. Examples: GRP-224

.Color =="Blue"

.Phone !="0"

(.Phone!="0")&&(.StateCode=="MA"||.StateCode=="VA"))

Run on Client This field appears only if you select Other Condition for the Visible field and a simple expression in the Condition field. SR-4450 SR-4339 B-21697 embedded

Select to indicate that the Condition field contains one more property comparison tests that will be evaluated on the user workstation in response to a client event. See Implementing dynamic form actions and the Client Event Editor. C-1990

Clear to indicate that the Condition field contains a when condition rule name or an expression to be evaluated once upon initial display of the form.

Required This box appears only for fields in cells on flow action rules and section rules. 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 section rules, 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. C-1197

NoteDon't select Required if the field is hidden or read-only. At runtime, users can see the error message but cannot alter the field. SR-4488

Wrap Text Select if the text in the cell is to be presented as multiple lines when the text is longer than the cell width. If the box is not selected, the text visible in the cell may appear truncated at runtime. R-19668
Read-Only Select to cause the property value to be 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. PROJ-283 Complete the next field to modify the effect of this checkbox.
Read-Only Condition SmartPromptOptional. Enter an expression involving another property, or identify the When Name key part of a when condition rule. PROJ-283 Specify one of three outcomes:
  • Leave blank to present the content in read-only mode always, regardless of the mode of the enclosing layout.
  • When condition rule — Enter the When Name key part of a when condition rule that determines the mode of this field at runtime. The system uses the Applies To key part of the current rule in rule resolution to locate the when condition rule, and executes the When rule once as it renders the form. Click the pencil icon (Pencil) to review or create the when condition rule.
  • Expression evaluated once — Enter an expression that returns true or false. This expression can involve multiple properties, function calls, and other syntax as supported by the <pega:when > JSP tag.

This field appears only when you select the Read Only checkbox.

  4. Complete the Cell properties panel — Advanced tab

Complete the Advanced tab to control the presentation and visibility of the field.

Field

Description

Width

TipAs a best practice, use SmartLayouts to achieve uniform width of cells throughout your application's forms. You can set the width of SmartLayout templates using the Application Skin wizard.

Optional. Enter a positive number for the width in pixels of this cell. (At runtime, normal browser processing for rendering tables determines the actual displayed width.)

This field appears only when the cell is not controlled by SmartLayout column restrictions. In that case, you can also adjust the width this column directly:

  1. Click a vertical wireframe cell border.
  2. Wait until the pointer shape changes (drag), then drag the border. PROJ-281
Height

TipAs a best practice, use SmartLayouts to achieve uniform height of cells throughout your application's forms. You can set the width of SmartLayout templates using the Branding wizard.

Optional. Enter a positive number for the height in pixels of this cell. (At runtime, normal browser processing for rendering tables determines the actual displayed height.)

This field appears only when all columns in the Layout are not controlled by SmartLayout column restrictions (that is, all columns have the None template). In that case, you can also adjust the height of a row directly:

  1. Click a horizontal wireframe cell border.
  2. Wait until the pointer shape changes (drag), then drag the border. PROJ-281
Default Value

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

Click the magnifying glass icon (magnifying glass) to start the Expression Builder. Click the pencil button (Pencil) to review a property rule.

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. B-14313 REJECTED MARTT 4/7/06

Read-Write Style

SmartPromptOptional. By default, when the work object form or flow action form appears in read-only mode, the CSS style named DataValueRead or DataValueRead RV2 applies. If this cell is not controlled by Smart Layout restrictions, you can enter another style name or select from those listed.

The SmartPrompt list shows all styles that start with the word Data. You are not limited to these styles.

Click the pencil icon (Pencil) to review the text file rule that defines the style sheet. Your application can override and extend this style sheet in an application text file rule.

Read-Only Style

SmartPromptOptional. By default, when the work object form or flow action form appears in read-only mode, the CSS style named DataValueRead or DataValueRead RV2 applies. If this cell is not controlled by Smart Layout restrictions, you can enter another style name or select from those listed.

The SmartPrompt list shows all styles that start with the word Data. You are not limited to these styles.

Click the pencil icon (Pencil) to review the text file rule that defines the style sheet. Your application can override and extend this style sheet in an application text file rule.

Inline Style

To apply inline styling to this cell only, type a CSS style definition in this field, or click the magnifying glass to access a Style Editor window. Styles you enter in this field supplement and override style elements defined in style sheets, according to normal CSS rules.

Inline styles are recorded in the generated HTML for the form; they do not alter the CSS definitions.

Using the Style Editor

You can select the font, color, font size, text align, vertical align, borders, margins, and other attributes of this cell using selection lists. The Style Editor maintains a preview of the resulting presentation. If you alter the style definition directly, click  Apply   to update the preview.

Click  OK   to record the style defined with the Style Editor in the panel.

Use Heading Styles Select to change the cell HTML element from <TD> to <TH>, with a resulting style change.

  Copying, deleting, duplicating, or moving a Text Area control

TipUse these Windows operations to speed development:

Up About Flow Action rules

Up About Harness rules

Up About Section rules