Row selection in actions

Objective

Sometimes actions associated with a grid apply to a subset of the rows included in the grid that is selected in runtime by the end user. This subset can be required to contain a single element, or can be allowed to contain multiple elements. K2BWebPanelDesigner includes an option in actions, through which the developer can achieve this in a very simple way.

How it works

Action nodes include a property called "RowSelection", which establishes whether the action should apply to one row (RowSelection=Single) or multiple rows (RowSelection=Multiple). When RowSelection has values Multiple or Single a check box column will appear in the grid:

RowSelectionRT
Row selection dialog in runtime

If the user clicks on the "Action" button, the action's code will be executed for the rows selected.

If RowSelection = Multiple an error message will appear if the action is executed and no rows are selected. This error can be changed in K2BWebPanelDesignerSettings, using the property "Error None Rows Selected".

If RowSelection = Single the behaviour is similar to the previous case, adding an error message which will appear if the final user selects more than one row. This error message can be changed in K2BWebPanelDesignerSettings using the property "Errow More Than One Row Selected".

If RowSelection = Multiple, the “Row Selection Scope” property will be shown. In this property the developer can choose if the action should apply to the selected items in the current page or all the selected items.

IMPORTANT: When using row selection, at least one of the grid's columns must be included in the selection key, using the Include in Selection Key property property in the column. This is used by K2BTools to generate code in the web panel that remembers which rows were selected by the user, and keeps the UI consistent when the grid is filtered or the page is changed.

How to implement actions with Row Selection

When actions have their “Row Selection” property set to a value different from “None”, Web Panel Designer generates code to validate that the grid’s selection matches the action’s specification. If those criteria are met, the “U_{ActionInternalName}” subroutine is executed once. Because of that, the developer does not have to implement these validations in the “U_{ActionInternalName}” subroutine.

When generating the “U_{ActionInternalName}” subroutine for the first time, a help message is included as a comment, describing the suggested structure for the subroutine’s code. As this comment may (and should) be deleted, the suggested structure is documented below.

The examples are based on a Web Panel with the structure shown below.

RowSelectionExampleStructure
Structure used in the examples

Implementing actions with Row Selection = Single

Implementing actions with Row Selection = Single is a simple task, as the developer only has to read the grid lines and see the value for the “&MultiRowItemSelected_{GridName}” variable.

Due to the validations performed before, the developer can be sure that one (and only one) line was selected.

RowSelectionSingleSampleCode
Single action sample code

Implementing actions with Row Selection = Multiple

Implementing these actions is a bit more complex, to allow the developer to switch between “Row Selection Scopes” seamlessly.

In this case, the suggested structure is different from the previous case as it does not include a “for each line” command. Instead, the code must iterate through the selected items using subroutines generated by Web Panel Designer, called “ResetMultirowIterator” and “GetNextMultirow”.

These subroutines load the selected items’ values in variables called “&S_{ColumnInternalName}”, which are used to navigate through the items without relying on the grid’s attributes/variables.

In the web panel used to create this samples, WebPanelDesigner created these variables: &S_CustomerId, &S_CustomerFirstName, &S_CustomerLastName, &S_CustomerDNI, &S_CustomerPrefix, &S_CustomerSex, &S_CustomerPhoto, and &S_CustomerMaritalStatus

RowSelectionMultipleSampleCode
Single action sample code

If this structure is used, the subroutines will iterate through the correct set depending on the “Row Selection Scope” defined by the developer.

Customizing the UI for grids with row selection

K2BTools contains several features to allow customization of grids with row selection:

  1. Including Selection Summary in grids.
  2. Including Adding a selected rows count textblock.
  3. Customizing the style object using Classes set by K2BTools when using row selection.