Code Library

The Janus GridEX control allows you to group the rows in a table in several ways with no limit to the number of groups the control is capable to hold. A user can drag column headers from the table and drop them into the "Group By Box" and the control automatically presents the data grouped by the chosen fields. When a record is added or updated, the control places that record in its proper position based on the current group settings.


Column Based Groups



The most common type of Grouping is by the values in a column. In this kind of grouping, the group rows are created accordingly to the values present in a column of the table.

Grouping can be done with any data source supported by the control even if the data source doesn’t have intrinsic sorting functionality. You can define which columns the rows are grouped by, at design time, programmatically or by user interaction.



At design time, you can add the groups in any table using the "GridEX Designer". The steps to add Column Based Groups at design time are as follows:





1) Right Click in a GridEX control and click at "Grid Designer..." menu. The GridEX designer will appear.

2) In the GridEX Designer, select the "Groups" node under the table to be arranged.

3) In the Right panel, Click in the "Add" button to add a new group and select the column to be grouped and the sort order for that key.

4) Repeat the add operation until you have finished adding groups and click OK in the designer.





Programmatically, you can create a GridEXGroup object specifying the column to be sorted and its sort order and add the group to the Groups collection of the table. For instance:

       Grouping by columns ‘Country" and ‘City’ in the root table of a GridEX control.

       Dim group As GridEXGroup

       Dim column As GridEXColumn

       'Removing any group present in the table

       GridEX1.RootTable.Groups.Clear()

       'get the column to be grouped

       column = GridEX1.RootTable.Columns("Country")

       'create the group

       group = New GridEXGroup(column, SortOrder.Ascending)

       'add the group to the Groups collection of the table

       GridEX1.RootTable.Groups.Add(group)

       'to group by more than one column, create as many groups

       'as are needed and add them to the Groups collection.

       'add another group

       column = GridEX1.RootTable.Columns("City")

       group = New GridEXGroup(column, SortOrder.Ascending)

       GridEX1.RootTable.Groups.Add(group)

Users are capable to group rows by dragging a column header from the table or from the Field Chooser to the "Group By Box" area. To prevent users from grouping by certain columns, you can set the AllowGroup property as False for those columns and to prevent grouping in all the columns of a table set the AllowGroup property in the GridEXTable object to False.

If you want to prevent the user from removing the groups you have defined, set the AllowRemove property for the Group as False.



By default, GridEX control groups rows comparing the values of cells. To group rows based on the displayed text in a cell, like when using columns that have a ValueList or a GridEXDropDown replacing the cell value with the text associated to that value, set the DefaultGroupInterval property of that column equal to GroupInterval.Text. For instance:

  Dim column As GridEXColumn

  column = GridEX1.RootTable.Columns("CategoryID")

  column.HasValueList = True

  'populating the value list in order to show the CategoryName

  'instead of the CategoryID in a column.

  column.ValueList.PopulateValueList(

_objDataSet.Categories.DefaultView, _

                             "CategoryID", "CategoryName")

  'specifying that the control should group this column using the

  'category name and not the CategoryID that is its real value.

  column.DefaultGroupInterval = GroupInterval.Text

For DateTime values, you can group rows by year, quarter, month, day, hour, minute or second. To have the same date column grouped by year first and then by month, you could add groups in rows specifying the GroupInterval in each GridEXGroup overwriting the default group interval specified in the column. For instance:

       Dim column As GridEXColumn

       Dim group As GridEXGroup

       'get the DateTime column to be grouped

       column = GridEX1.RootTable.Columns("Date")

       'grouping the column using a year interval

       group = New GridEXGroup(column, SortOrder.Ascending, _

                                                                                   GroupInterval.Year)

       'also, you might want to change the format for that group:

       group.GroupFormatString = "yyyy"

       GridEX1.RootTable.Groups.Add(group)

       'then grouping the same column using a month interval

       group = New GridEXGroup(column, SortOrder.Ascending, _

                                                                                   GroupInterval.Month)

       'also, you might want to change the format for that group:

       group.GroupFormatString = "MMM yyyy"

       GridEX1.RootTable.Groups.Add(group)

       'and finally grouping the column by its date

       GridEX1.RootTable.Groups.Add(New GridEXGroup(column, _

                                   SortOrder.Ascending, GroupInterval.Date))

The options available for group intervals are:
Value
(Default) Groups are calculated using the value of the cell.

Text
Groups are calculated using the text of a cell. This setting is particularly useful when grouping columns with ValueList or DropDowns that replace Id values for a text associated to it or when you assign the Text property of a cell in the LoadingRow event.

Alphabetical
Groups are calculated using only the first character of the text of a cell.

Date
Groups are calculated using only the date portion of a DateTime value. The time portion is ignored. (Use this option only when the Type of the values in the column is DateTime)

Month
Groups are calculated using only the month and year portions of a DateTime value. The day and time portions are ignored.

(Use this option only when the Type of the values in the column is DateTime)

Quarter
Groups are calculated based using the quarter and year that a DateTime value belongs.

(Use this option only when the Type of the values in the column is DateTime)

Year
Groups are calculated using only the year of a DateTime value. The month, day and time portions are ignored.

(Use this option only when the Type of the values in the column is DateTime)

Hour
Groups are calculated using the date and the hour of a DateTime value. Minutes and seconds are ignored.

(Use this option only when the Type of the values in the column is DateTime)

Minute
Groups are calculated using the date, the hours and the minutes of a DateTime value. Seconds are ignored.

(Use this option only when the Type of the values in the column is DateTime)

Second
Groups are calculated using the date, the hours, the minutes and the seconds of a DateTime value.




When the GridEX control is holding more than one table in a hierarchical fashion, Parent Tables can be grouped based on the values present in the columns of one of its child tables by setting the AllowChildTableGroups property in the GridEXTable.



The GridEX Control is also capable to group columns with more than one value. A MultipleValues Column can be used to hold the values of a many-to-many relation between tables in the DataSource. When grouping by a MultipleValues Column a record in the table could belong to more than one groups and the control will present a copy for those repeated records in each of the corresponding groups. When an edition in those copied record is made, the control will automatically reflect the changes in each copy.



Custom Groups (Composite Columns)



Another way of grouping the values in a table is by defining more than one field to create a single group. In this kind of grouping the control will create one group per every combination of the values in the columns defined for grouping. For instance, if a table contains columns "Country" and "City", and if a CompositeColumns Group were defined for such columns, the control will present in one Group all the records whose values are identical for both fields.

A CustomGroup can be assigned to one or more Columns by setting its CustomGroup property in order to apply such custom grouping when the users drop the column header of such column into the GroupByBox area of the control.

At design time, you can define a CompositeColumns group in a table using the "GridEX Designer". The steps to add groups at design time are as follows:





1) Right Click in a GridEX control and click at "Grid Designer..." menu. The GridEX designer will appear.

2) In the GridEX Designer, select the "CustomGroups" node under the table to be arranged.

3) In the Right panel, Click in the "Add" button to add a new CustomGroup.

4) Select CompositeColumns as the value for the CustomGroupType property

5) Click at the button in the CompositeColumns property and select the columns you want to use for creating the groups from the list of Fields present in table.

6) Set the ShowInFieldChooser property for the CustomGroup as True if you want to allow the user to regroup for this CustomGroup if it were removed from the "Group By Box".

7) In the GridEX Designer, select the "Groups" node.

8) In the Right panel, Click in the "Add" button to add a new group and select the CustomGroup you just created in the previous steps.

9) Write the HeaderCaption which contains the text that will appear in the GroupByBox for such Group.







Custom Groups (Conditional Groups)



Conditional Groups (ConditionalGroupRows) provides you complete control over the way the records in a Table are presented in groups. In this kind of grouping the control will present a collection of GroupRows you have defined. The GroupRows collection will hold the records that match the criteria specified in a Condition specified for each group row. You can predefine an unlimited number of GroupRows and the control will not show those GroupRows if there are no records that match the criteria specified for a certain group unless you set its ShowWhenEmpty property as True. The GroupRows will be shown in the same order in which they were added to the collection.



Depending on the criteria specified in the Condition for the collection of GroupRows, a record could fit in more than one group and the control will present a copy for those repeated records. When a record in the table does not match the criteria specified for the GroupRows, the control will filter those records out of View.


At design time, you can define ConditionalGroupRows in a table using the "GridEX Designer". The steps to add groups at design time are as follows:





1) Right Click in a GridEX control and click at "Grid Designer..." menu. The GridEX designer will appear.

2) In the GridEX Designer, select the "CustomGroups" node under the table to be arranged.

3) In the Right panel, Click in the "Add" button to add a new CustomGroup.

4) Select ConditionalGroupRows as the value for the CustomGroupType property

5) Click at the button in the GroupRows property to present a window where the GroupRows will be defined.

6) Click in the "Add" button to add a new GroupRow.

7) Define the Condition and the GroupCaption for the GroupRow

8) Repeat the steps 6 and 7 until you have finished adding GroupRows and click OK in the form.

9) Optional: You could easily create a complementary GroupRow for all the other GroupRows defined in the collection, by creating a new GroupRow with its ShowRemainingRows property equal to true. Note: Only one row in the GroupRows collection can have its ShowRemainingRows property as true.

10) Set the ShowInFieldChooser property for the CustomGroup as True if you want to allow the user to regroup for this CustomGroup if it were removed from the GroupByBox.

11) In the GridEX Designer, select the "Groups" node.

12) In the Right panel, Click in the "Add" button to add a new group and select the CustomGroup you just created in the previous steps.

13) Write the HeaderCaption which contains the text that will appear in the GroupByBox for such Group.

Source Of Information : Janus v3.5 Help Files for VS 2008