Harness and Section forms Adding a DataGrid control

The DataGrid control is deprecated. Update an existing DataGrid to a Grid control. For guidelines on upgrading, see Upgrading deprecated and outdated controls on the PDN.

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

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 Adding a Text Input control — General tab and Adding a Text Input Control - Advanced tab 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 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	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	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	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	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

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

About Flow Actions

About Harnesses

About Sections