EDT:DataGrid Widget

 Introduction

A Rich UI dataGrid widget defines an array of row values in a table. This topic gives general information about the widget and then provides reference detail.

An understanding of the data grid requires that you be familiar with the following issues:
• How to define column headings and data rows.
• How to define a behavior, which is a property that takes an array of functions. The functions for a given behavior run in array-element order when the grid is being rendered.
• How to define a listener, which is also a property that takes an array of functions. The functions for a given listener run in array-element order in response to a user action such as a click or, in some cases, in response to a function call that selects or deselects a row or that updates a check box.
• How to customize a mechanism for sorting the grid by column.
• How to customize a formatter to DataGridColumn.
• Other tips when using DataGrid, Paging, Using Data Loader, etc.

Behaviors and listeners can affect style characteristics and can invoke logic of various kinds; for example, to cause a sort by column; to access a service; to calculate a value and place it into a grid column; or to configure a widget and place it into a grid column. You can build on these ideas in various ways; for example, you might do as follows:
1. Access a user ID from a row of the data grid.
2. Use that ID in a REST service invocation that returns a photograph to a callback function.
3. Embed that photograph in an image widget, which is defined globally in the handler.
4. Place that widget in a data grid column, in the same row as the user ID.

You can use the useful properties, functions and extensions of DataGrid to do many thing you want. I’m sure you can not wait any longer to start the DataGrid travel. So let’s start form creating a RUI DataGrid in RUI Handler.

Create a Simple DataGrid

In this section we will provide a step by step introduction about creating a DataGrid in EDT.
'1. 'Right click on a EGL project/package --> New --> Handler. The New EGL Handler wizard will pop up.

Fill the Name field and select Rich UI Handler as the templates, the click Finish. The Hand will be created to the target package.

'2. 'When the Handler created, it will be opened in EGL Rich UI Editor automatically. And also you can open it by double click or right click on the handler  Open With  EGL Rich UI Editor.
Switch to design view, the Palette is on the right side of the EGL Rich UI Editor. You can find the DataGrid widget in “Display and Input” tab of the Palette. Then you can drag the DataGrid from the Palette to anywhere of the design panel.
When the mouse up, the “New Variable” wizard will pop up.

Type in the Variable name for the DataGrid and then click OK. The DataGrid will appears in design panel. And the source code have also changed.

3. Define a Record part to be the basis of an array of records. Each record holds a set of values that you want to display in a single row of a data grid. You can create a new record source file to maintain the record or just paste it at the bottom of the RUI Handler.

Record Stock 
   Symbol string;
   NumShares int;
   Quote  decimal(5,2);
   SelectQuote boolean;
end

4. Declare the array of data records, as in the following example:

stockList Stock[] =[new Stock{SelectQuote = false, Symbol = "Company1", Quote = 100.00, NumShares = 40},
                      new Stock{SelectQuote = false, Symbol = "Company2", Quote = 200.00, NumShares = 10}];

5. Change the DataGrid declaration to the target record structure.

DataGrid DataGrid{layoutData = new GridLayoutData{row = 1, column = 1}, behaviors =[], headerBehaviors =[], columns =[
                    new DataGridColumn{name = "Symbol", displayName = "Company Symbol"},
                    new DataGridColumn{name = "Quote", displayName = "Price Per Share"},
                    new DataGridColumn{name = "NumShares", displayName = "Number of Shares"},
                    new DataGridColumn{name = "Total", displayName = "Value of Shares", formatters =[totalFormatter]
                 }]};

Each of the first three declarations of type DataGridColumn references a record field in the array of Stock records. The fourth declaration identifies a calculated column, which is a column that has no corresponding record field; in this case, no record field named Total.
The order of the DataGridColumn elements determines the order in which the columns are displayed.
For the data property, assign the array of records of type Stock. Here is an example setting:
     DataGrid.data = stockList as any[];

You can just put this code in function start. Each element in the array provides a subset of the data required for a row in the data grid.

6. Add formatter function You set the behaviors and listeners by assigning values to properties. Each of those properties is related to a Delegate type, which identifies the parameter list and return value that are required for any of the functions assigned to the property. In the example, the DataGridColumn formatters property is set for the fourth column and causes the invocation of a function that takes three parameters and has no return value. Here is the function:

function totalFormatter(class string inOut, value string inOut, rowData any in)
    // display the total value of the shares after calculating the value 
    // from the content of two other columns in the same row
        value = rowData.NumShares as int * rowData.Quote as decimal(5, 2);
end

The invocation of a function referenced in the formatters property occurs once per row, before the grid is rendered. The content of the entire row is available in the third parameter, and you can update the column-specific cell by setting either the first parameter, which controls the CSS class, or the second parameter, which controls the value.

7. Switch to Preview

The DataGrid should have shown in the preview mode.

DataGridColumn fields

You assign an array of records of type DataGridColumn when you set the columns property for a data grid. Each of those records includes the following fields:

• alignment: an constant integer that affects the horizontal alignment in the displayed column:

DataGridLib.ALIGN_LEFT (the default)  ---  The column content is left aligned
DataGridLib.ALIGN_RIGHT   ---   The column content is right aligned.
DataGridLib.ALIGN_CENTER   ---   The column content is center aligned.

• columnComparator: references a comparator function during a column sort. A comparator function is invoked repeatedly to order the cell content.

Here is the Delegate part to which a custom function must conform:

Delegate ColumnComparator(data1 any in, data2 any in) returns (int) end

data1: The content of the first cell being compared
data2: The content of the second cell. The function returns the following integer value:
        -1 if the content of the first cell is less than the content of the second.
        1  if the opposite is true.
        0  if the content of the two cells are equal.

Here is an example function, which might be used if the previous example were extended to include company names Company3 through Company10:

Function CompareTwo(myFirst ANY in, mySecond ANY in) returns (int)
   if ( (myFirst as string )[8:8] == "6")
      return(-1);
   else
      return(1);  
   end
end

If the columnComparator property refers to the CompareTo function, the user's click places Company6 at the top or bottom of the column.

• displayName: a string to display as the column title. If the displayName field is not specified, the column title is the value of the name field.
• enableSorting: a Boolean value to indicate whether the user can sort the column with a click. The default value is true. the sort is affected by the setting of the ignoreCase property, but only if you do not specify the columnComparator property.
• formatters: an array of functions that run in array-element order before the grid is rendered. These functions run once for every cell in the column.

Here is the Delegate part to which each function must conform:

Delegate CellFormatter(class String inout, value String inout, rowData any in) end

class: The CSS class for the cell in the column.
value: The cell content, which is always of type STRING. If the content is a checkbox, the value is true or false.
rowData: The data of the row in which the cell resides. The example in the Introduction shows how to handle the input.
          The functions for the formatters field are invoked in the order in which the DataGridColumn entries are defined in the DataGrid columns property. Those             functions run before the functions specified in the following DataGrid properties, which are listed in runtime order: headerBehaviors, behaviors, and               editingBehaviors.
          A set of functions are provided for use with the formatters property. For details, see the following file in the com.ibm.egl.rui project,                           com.ibm.egl.rui.widgets package: DataGridFormatters.egl.

• headerAlignment: an integer value that affects the horizontal alignment in the displayed header. The values are as follows:

DataGridLib.ALIGN_LEFT (the default)   ---   The column content is left aligned
DataGridLib.ALIGN_RIGHT   ---   The column content is right aligned.
DataGridLib.ALIGN_CENTER   ---   The column content is center aligned.
You can set all the column headers by including a entry like the following one in the CSS file, specifying left, center, or right for the text-align attribute:

.EglRuiDataGridHeaderCell {
   text-align: center;
}

• ignoreCase: a Boolean value to indicate whether the case of the column content is ignored during the default sort. The default is false. The property value has an effect only if you do not set the columnComparator property.
• name: a string that is both the default column title and the name of the record field that provides the column value.
• sortDirection: one of the following constants, to indicate what the user's next request for a sort will do:

DataGridLib.SORT_UP (the initial default)   ---   The user's click will sort the column in ascending order.
DataGridLib.SORT_DOWN   ---   The user's click will sort the column in descending order.
DataGridLib.SORT_NONE   ---   The user's click will have no effect.
You might access the sortDirection field in a comparator function.

• width: an integer that specifies the column width, in pixels.