Sorting Overview (igGrid)

Overview

The igGrid control sorting feature enables single or multiple column sorting in an ascending or descending order.

In this topic

This topic contains the following sections:

• Sorting Persistence
• Sorting Modes
• Configuration Considerations
• Enabling Sorting
• Column Settings
• Remote Sorting
• API Usage
• Client-Side events
• Sorting options
• List of Sorting CSS classes
• Related Content

Sorting Persistence

Persisting Sorting between igGrid re-bindings is made easy in version 14.1 and in fact replaces the previous default behavior.

Note: Sorting persistence is true by default. This is a breaking change.

When you enable igGridSorting you are already using it in a persist mode. This means that after explicitly calls of dataBind(), that persistence is applied for UI and data source view (the sorting indicators and the CSS classes are applied, the data source remains sorted)

Sorting persistence is implemented for igHierarchicalGrid too.

The following sample demonstrates the persistance capabilities of the Sorting feature.

If you would like to retain the previous behavior of sorting being cleared after user re-binds the igGrid, you can do this by disabling the feature through the persist option as shown in the code snippet below:

In JavaScript:

features: [
  { 
     name: "Sorting", 
     persist: false 
  }
]

Sorting Modes

Sorting can be configured to operate either locally or remotely. In the first case, sorting is done entirely on the client, without the need of any server requests. In the case of remote sorting, the grid encodes the necessary URL parameters so the server can retrieve information about which columns must be sorted.

Configuration Considerations

• Sorting may be configured to support single or multiple column sorting. Sorting modes are controlled by changing the mode option to single or multiple.
• Multiple Sorting allows you to remove sorting.
• You can unsort a column, by pressing SHIFT + click on the header of the igGrid column you want to unsort.
• The Multiple Sorting Dialog shows the sorting order of the columns. The column, by which the most recent sorting has been performed, is displayed at the top of the Sorting Dialog list thus moving the previous sort columns down. This way, the “history” of the performed sortings is retained in the list indicating at the same time the second, third and so on sort order columns. For more information about the Sorting-Dialog-specific properties and events refer to the Multiple Sorting Dialog topic.
• You can control sorting on a column-level by modifying the columnSettings object. For example you can disable sorting for a particular column, or specify that you would like it to be sorted in an ascending order by default.
• Sorting can also be case sensitive, which can be turned on by setting the caseSensitive option to true. This options works only for local sorting.
• Once the sorting widget is instantiated, it modifies the column header by injecting markup that allows for the various active, focus and sorted styles to be applied, including the sort indicator.
• Sorting is implemented as a jQuery UI widget, which follows the lifecycle of any jQuery UI widget.
• The grid framework is responsible of creating and destroying the sorting widget.
• All sortable columns can be sorted and navigated through the keyboard using the TAB and Shift+TAB keys.

Figure 1: The igGrid control sorting UI

Enabling Sorting

The sample below demonstrates how to enable the Sorting feature:

The following code snippet shows how to enable Sorting in ASPX (MVC)

In ASPX (MVC):

<%= Html.Infragistics().Grid(Model).ID("grid1").Columns(column =>
    {
        column.For(x => x.EmployeeID).HeaderText("Employee ID").Width("15%");
        column.For(x => x.FirstName).HeaderText("First Name").Width("20%");
        column.For(x => x.LastName).HeaderText("Last Name").Width("20%");
        column.For(x => x.BirthDate).HeaderText("Birth Date").Width("15%");
        column.For(x => x.City).HeaderText("City").Width("15%");
        column.For(x => x.PostalCode).HeaderText("Postal Code").Width("15%");
    }).Features(features => {
        features.Sorting().Type(OpType.Local).CaseSensitive(true);
    })
    .Height("500")
    .DataSourceUrl(Url.Action("PagingGetData"))
    .DataBind()
    .Render()%>

If you would like to provide a custom sorting function, please refer to the customSortFunction option.

Column Settings

Each column is configurable with the columnSettings options as listed in Table 1.

Table 1: The columnSettings object

In JavaScript:

$("#grid1").igGrid({
    columns: [
        { headerText: "Product ID", key: "ProductID", dataType: "number" },
        { headerText: "Product Name", key: "Name", dataType: "string" },
        { headerText: "Product Number", key: "ProductNumber", dataType: "string" },
    ],
    width: '500px',
    dataSource: products,
    features: [
        {
            name: 'Sorting',
            columnSettings: [
                    {columnKey: 'ProductID', allowSorting: false}
               ]   
        }
    ]
});

Remote Sorting

You can control how the URL is encoded when sorting is performed by setting the sortUrlKey option. The sortUrlKey is null by default, therefore the encoding follows oData standards for URI format, as described here:

http://www.odata.org/documentation/odata-version-2-0/uri-conventions/

API Usage

In order to sort a column programmatically, you can do this in the following way:

Listing 5: Programatically sorting a column

In JavaScript:

$('#grid1').igGridSorting('sortColumn', 'ProductID', 'asc');

The applied sorting expressions can be retrieved from the data source of the grid. In order to get them programmatically, you can use the following:

Listing 6: Retrieving the applied sorting expressions

In JavaScript:

var expressions = $('#grid1').data('igGrid').dataSource.settings.sorting.expressions;

Listing 7: Retrieving the columnSettings object

In JavaScript:

var sorting = $('#grid1').data('igGridSorting');
var settings = sorting.options.columnSettings;

Client-Side events

You can bind to client-side events to the Sorting feature in two ways, which are described in Listing 8 and Listing 9, respectively.

Listing 8: Binding to client-side events from anywhere in your application

In JavaScript:

$("#grid1").bind("iggridsortingcolumnsorted", handler);

Note: If you would like to bind using the approach described in Listing 8, you must use the jQuery delegate method instead of bind if Sorting is not yet instantiated.

Listing 9: Binding to client-side events by specifying the event name as an option when you initialize the Sorting feature (case sensitive)

In JavaScript:

$("#grid1").igGrid({
    columns: [
        { headerText: "Product ID", key: "ProductID", dataType: "number" },
        { headerText: "Product Name", key: "Name", dataType: "string" },
        { headerText: "Product Number", key: "ProductNumber", dataType: "string" },
    ],
    width: '500px',
    dataSource: products,
    features: [
        {
            name: 'Sorting',
            columnSorted: handler
        }
    ]
});

//Handler code
function handler(event, args) {

}

Note: All "ing" events are cancellable. In order to cancel an "ing" event, its respective event handler must return false.

The grid Sorting feature exposes the client-side events as detailed in Table 2.

Note: In the following Table 2, the events specific to the Multiple Sorting Dialog are not listed. They are available in the Multiple Sorting Dialog topic.

Table 2: Argument object definitions for the Sorting feature events

Sorting options

The table in Listing 3 summarizes all sorting options available to instantiate the Sorting widget.

Note: In the following Table 3, the properties specific to the Multiple Sorting Dialog are not listed. They are available in the Multiple Sorting Dialog topic.

Table 3: Sorting widget options

List of Sorting CSS classes

Table 4 specifies all CSS classes applied to various parts of the Sorting UI. Note that ui-state-default, ui-state-active, ui-state-hover, ui-state-focus are classes defined by the jQuery UI CSS framework.

Table 4: CSS classes applied to the Sorting UI

Related Content

Topics

• igGrid Overview