Infragistics(R) NetAdvantage(R) jQuery
igGrid Sorting
E-mail your feedback on this topic.

Glossary Item Box

Overview

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

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

Figure 1: The igGrid control sorting UI

Enabling Sorting

In order to get started with Sorting, you first need to include the necessary JavaScript and CSS dependencies. The easiest way to do that is to use the combined / minified version of the scripts and styles.

Listing 1: Necessary CSS and JavaScript references you need to include in your application


In HTML:

<link type="text/css" href="infragistics.theme.css" rel="stylesheet" />
<link type="text/css" href="infragistics.css" rel="stylesheet" />
<script type="text/javascript" src="jquery-1.4.4.min.js"></script>
<script type="text/javascript" src="jquery-ui.min.js"></script>
<script type="text/javascript" src="jquery.tmpl.js"></script>
<script type="text/javascript" src="infragistics.js"></script>
Listing 2: Minimal set of CSS and JavaScript references (not minified and combined) – needed only for sorting

In HTML:


<script type="text/javascript" src="ig.util.js"></script>
<script type="text/javascript" src="ig.dataSource-en.js"></script> <script type="text/javascript" src="ig.dataSource.js"></script> <script type="text/javascript" src="ig.ui.shared.js"></script> <script type="text/javascript" src="ig.ui.grid-en.js"></script> <script type="text/javascript" src="ig.ui.grid.framework.js"></script> <script type="text/javascript" src="ig.ui.grid.sorting-en.js"></script> <script type="text/javascript" src="ig.ui.grid.sorting.js"></script>

The “*-en.js” files contain localized strings for various parts of the UI. If you would like to localize the feature in a different language, you can just replace the selection-en.js with your localized version. You only need to change the values in the file; the keys need to remain the same.

Listing 3: Sample grid code for sorting


In Javascript:

$("#grid1").igGrid({
    columns: [
        { headerText: "Product ID", key: "ProductID", dataType: "number" },
        { headerText: "Product Name", key: "Name", dataType: "string" },
        { headerText: "ProductNumber", key: "ProductNumber", dataType: "string" }
    ],
dataSource: “adventureWorks.php”,
    responseDataKey: 'Records',
    features: [
        {
            name : 'Sorting',
            type: "local",
            columnSettings: [
            ]
        }
    ]
});



In HTML:

<table id="grid1"></table>


In ASPX (MVC):

  <%= Html.Infragistics().Grid(Model).ID("grid1").Columns(column =>
        {
            column.For(x => x.ProductID).HeaderText("Product ID").Width("100px");
            column.For(x => x.Name).HeaderText("Product Name").Width("200px");
            column.For(x => x.ProductNumber).HeaderText("Product Number").Width("200px");
            }).Features(features => {
                features.Sorting().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

Property name (default values in parenthesis) Description
columnKey( string col name) Data key of the column
allowSorting (true) Specifies if this column is allowed to participate in sorting
firstSortDirection (undefined) Sorting direction when the column is first clicked
currentSortDirection (undefined) Initial (default) sorting direction. When invoked at runtime, gives the current direction of sorting for the particular column.

Listing 4: Example usage of columnSettings


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/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');

Listing 6: 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 7 and Listing 8, respectively.

Listing 7: 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 7, you must use the jQuery live method instead of bind if sorting is not yet instantiated.

Listing 8: 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 columnSorting feature

Event Name Args
columnSorting

columnKey: Column key

owner: Reference to the instance of igGridSorting widget

direction: New sorting direction

columnSorted Same as columnSorting

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

Option name and default value Description
type (“remote”) Type of the sorting with respect to where data comes from – either client or server. This setting delegates directly to the igDataSource instance used by the grid. You can have binding to a remote service, with local sorting, for example. Values are remote or local.
applySortedColumnCss (true) If false, the sort will not apply a special “sorted” style to all TD cells of the sorted column.
caseSensitive (false) Enables/disables case sensitive sorting support
sortUrlKey (null) The key to encode in the url, which delegates to the data source control. If no URL is set, the oData conventions are used.
sortUrlKeyAscValue (null) Delegates to the igDataSource control – states how the URL value for “ascending” state is encoded
sortUrlKeyDescValue (null) Same as sortUrlKeyAscValue
mode (“single”) Sorting can be multiple or single (default). When it is single, all previous sorting states are cleared.
firstSortDirection (‘ascending’) Direction – asc or desc – when the column is clicked for the first time, and hasn’t been sorted before.
sortedColumnTooltip ('sorted ${direction}') Format of the tooltip “title” attribute applied on the TH
unsortedColumnTooltip ('click to sort column') Same as unsortedColumnTooltip but when the column is unsorted
columnSettings ([]) A list of column specific sorting settings, see Table 4
customSortFunction (null)

Custom sorting function that accepts as parameters the following:

1. The data array to sort

2. An array of fields definitions to sort by, and

3. The sorting direction, “asc” or “desc”.

Should return the sorted data array.

Example:

function myCustomSortFunction (data, [{fieldName: “ProductID”,dir: “asc” }], “asc”) {

// …

return sortedData;

}

(The third parameter if optional if every passed field definition already contains the “dir” property.

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

UI AREA Overview of the rendered UI area List of CSS classes applied to this area
sortableColumnHeader Applied to the column’s TH

ui-iggrid-sortableheader

ui-state-default

sortableColumnHeaderActive Applied to the column’s TH when keyboard navigation is used to TAB through the headers , and ENTER or SPACE key is used, or when the header is simply clicked with the mouse

ui-iggrid-sortableheaderactive

ui-state-active

sortableColumnHeaderHover Applied to the sortable column’s TH on mouse over

ui-iggrid-sortableheaderhover

ui-state-hover

sortableColumnHeaderFocus Applied when keyboard navigation is used (just TAB through the headers), without pressing ENTER or SPACE – that is’ this corresponds exactly to the browser’s focus.

ui-iggrid-sortableheaderfocus

ui-state-focus

ascendingColumnHeader Applied in addition to the other classes to the column header TH when the column is sorted ascending ui-iggrid-colheaderasc
descendingColumnHeader Applied in addition to the other classes to the header TH when the column is sorted descending

ui-iggrid-colheaderdesc

ascendingColumn Applied to all the column TD’s , when the column is sorted ascending ui-iggrid-colasc
descendingColumn Applied to all the column TD’s when the column is sorted descending ui-iggrid-coldesc
sortIndicator Applied to the indicator icon SPAN element (background image and background position determines the exact portion of the sprite) ui-iggrid-colindicator
sortIndicatorAscending Applied to the icon SPAN when the indicator is ascending. This span is a child element of the TH and is wrapped in an A tag.

ui-iggrid-colindicator-asc

ui-icon

ui-icon-arrowthick-1-n

sortIndicatorDescending Same as sortIndicatorAscending but when descending

ui-iggrid-colindicator-desc

ui-icon

ui-icon-arrowthick-1-s


Related topics

igGrid Overview