Harness, Section, and Flow Action forms
Adding a DataGrid control

For new development in V6.1+, use of the Grid layout provides additional features and improved performance and flexibility compared to the V5.5 DataGrid control. See Adding a Grid layout.

Use a DataGrid control to allow users to view or edit values of a Page List or Value List property, as an alternative to the Row Repeat, Column Repeat or Tabbed Repeat control.

Basics

The DataGrid control provides application users with an attractive, compact table or matrix for reviewing, editing, and sorting tabular data. Depending on configuration details, the control allows substantial editing to occur within a browser window, with bulk updates occurring only when the form is submitted. (Alternatively, using AJAX calls, server updates can occur a row at a time.)

Based on the standard control DataGrid and the <pega:dataGrid > JSP tag, this control provides three modes:

Cells edit — The user can change the value in any cell. Changes are posted to the clipboard when focus leaves a row, or when focus leaves the control, depending on parameters.
Inline section — The user can update a single row at a time. All fields in a row appear in a separate, editable area, defined by a section.
Pop-up section — The user can update a single row at a time. All fields in a row appear in a separate, editable modal window, defined by a section.

Runtime interaction

Several user actions are available at runtime, depending on DataGrid parameters:

Click to append a new row to the grid.
Click to insert a new row above the selected row.
Click to delete a selected row or rows.
Click inside the numbered index column to select a row. Use SHIFT+click or CTRL+click to select multiple rows.
Use Copy (CTRL+C) and paste (CTRL+V) operations on rows.
Drag and drop to reorder selected rows.

Examples

For an example of the Cell Edit mode, review the Scheduled Absence area on the Work Settings tab of any Operator ID form. The contents of this tab of the Operator ID form are defined in the standard section named Data-Admin-Operator-ID.WorkSettings.

For an example of the Pop-up Section mode, examine the top grid in the standard section PegaAccel-Task-GenerateApp.Correspondence (part of the Application Accelerator). The pop-up section, which allows entry of a single row of the grid, is Embed-Accel-CorrespondenceCorrForGeneration.

Step 1. Plan

Identify the Page List or Value List property to be presented as a DataGrid. For a Page List, determine the Page Class of the property and the embedded Single Value properties that are to appear as columns in the grid.

The DataGrid control updates property values; it does not add a property to the clipboard. Evolve your application so that the Value List or Page List property is present on the clipboard — even if it has no rows — when the DataGrid is presented to the user.

Step 2: Define a section to allow editing of one row

If the property is a Page List and you plan to allow editing of an element through a section display, create a section to allow user input and editing. Set the Applies To key part of this section to the Page Class of the property.

Step 3. Add a placeholder into the cell

Access the Layout tab of the harness or section that is to contain the control, or the Form tab of the Flow Action form. Click the down arrow (

) in the Basic control group (

) and drag a Text box control

and drop it in the destination cell.

Step 4: Complete the Cell Properties panel

Complete the Cell Properties panel for the text box control. Complete the Property field with the Page List or Page Group property you identified in Step 1.

Set the Control field to DataGrid.

Complete the General tab and Advanced tab parts of the Cell Properties panel to meet application needs. See Completing the Layout tab — Adding a Text Input control — General tab and Completing the Layout tab — Adding a Text Input control — Advanced tab.

Ensure that the width and height of the panel are sufficiently large to support the initial display of the DataGrid.

Step 5: Supply control parameters

Click the magnifying glass icon () at the right of the Display As field. Enter parameter values for the DataGrid control:

Field

Description

Data Grid Columns Property Type

Select Page List or Value List.

Page List Property Name or Value List Property Name

SmartPrompt Identify the Value List or Page List property. This property must be present on the clipboard when the DataGrid is presented; the property may be empty. If the property is not on the primary page of the harness, section, or flow action, include the page name before the property name.

Applies To

SmartPrompt Identify the Applies To key part of the property.

Width

Optional. Enter a width in pixels for the DataGrid display. If left blank, the system determines the width based on current contents of the control.

Height

Enter a height in pixels for the DataGrid display.

Ordered DataGrid

Select to allow the user at runtime to insert, delete, and move rows using drag and drop, copy, and paste operations. The index value (an integer starting at 1) appears in a read-only column.

Leave cleared to allow the user at runtime to sort rows by any column, by clicking the column header.

In either case, the order of rows when the form is submitted and saved becomes the order of values in the Value List or Page List property.

Enable Editing

Select Cells Edit, Inline Section or Pop-up Section to control the type of editing available at runtime.

Custom Section for Row Editing

SmartPrompt Optional. If you selected Inline Section or Pop-up Section for the Enable Editing field, identify here the section you developed in Step 2 above.

Append/Insert
buttons visibility

Select:

Visible — To make the Append and Insert buttons visible at runtime to users.
Hidden — To prevent users from adding rows at runtime
Other Condition — To show, or hide the Append and Insert buttons depending on the one-time evaluation of a when condition rule.

Condition

SmartPrompt If you selected Other Condition for the previous field, identify here a when condition rule that determines whether the buttons are visible.

Delete buttons visibility

Select:

Visible — To make the delete buttons visible at runtime to users.
Hidden — To prevent users from deleting rows at runtime.
Other Condition — To show, or hide the delete buttons depending on the one-time evaluation of a when condition rule.

Condition If you selected Other Condition for the previous field, identify here a when condition rule that determines whether the delete buttons are visible.

Row Selection

Select Single or Multiple to control whether the user at runtime can select (and drag to move) only one row or multiple rows.

Users can use CTRL-click to select multiple, non-contiguous rows, or SHIFT-click to select all rows between the current row and the row most recently selected (whether above or below the current row). These actions are similar to those used with other familiar Windows controls.

Immediate Update of Data Source

If the Enable Editing value is Cells Edit, select to cause each updated row to be sent from the user browser window to the PRPC server, as soon as focus leaves the row. This approach uses AJAX technology to communicate the changes to the server.

Use with caution. Your application may need to provide a way for users to explicitly "undo" such rows. The clipboard retains these updates unless your application removes them. The next Commit operation causes the changes to be saved into the database.

If not selected, user edits are sent to the PRPC server only when the user form (or flow action form) is submitted.

This checkbox is visible only when the Enable Editing value is Cells Edit.

Data Columns

Use this DataGrid control to identify and describe the columns of the DataGrid control you are building.

Complete at least one row. Order is significant in this array; at runtime, the top row of this array becomes the leftmost column of the DataGrid.

Label	Description
Property Name	Enter the property name with no preceding period.
Caption	Optional. Enter a word or brief phrase to identify this column on the grid.
Width (px)	Optional. Enter a default width for this column in pixels. If blank, the control allocates column width.
Editable	Select to allow users to enter or update values in this column at runtime.
Editor	Select to control how text input to this field is presented. Select: `Text Field` — Each cell in this column operates as an HTML `<INPUT TYPE="TEXT" ..>` element when in focus. `Text Area` — Each cell in this column operate as an HTML `<TEXTAREA>` element, accepting multiple lines of input, when in focus `Checkbox` — Each cell operates as an HTML `<INPUT TYPE=CHECKBOX ..>` element when in focus. `Radiobutton` — Each cell operates as a radio button group (HTML `<INPUT TYPE=RADIO ..>`) `Combobox` — Each cell operates as an HTML `<Select ..>` element when in focus. `Control` — Support editing based on the control identified in the next column. If the Editable checkbox is not selected, then all cells in the column are read-only.
Control	Optional. If you selected `Control` for the Editor field, identify a control to support editing. Four rules are valid: Date-Calendar DateTime Default OpenRuleAdvanced Click Params to enter parameters for these controls.

Step 6: Save and Test

Click OK to close the control parameters window.
Click OK or Apply to close the Cell Properties panel.
Save the harness, section, or flow action form.
Test the DataGrid.

About Flow Actions

About Harnesses

About Sections

Harness, Section, and Flow Action forms Adding a DataGrid control

Examples

Field

Description

Label

Description

Harness, Section, and Flow Action forms
Adding a DataGrid control