Paging (igGrid)

In this topic

This topic contains the following sections:

• Overview
• Data Formats
• Enabling Paging
• ASP.NET MVC Code
• Remote Paging
• API Usage
• Client-Side Events
• Location of Paging UI Elements
• Known Issues and Limitations
• Paging Properties
• Paging CSS Classes
• Keyboard Interactions
• Related Content
• Sample

Overview

The Ignite UI for jQuery™ grid, or igGrid, Paging feature allows you to divide your data in pages so that you can achieve better performance by fetching only a predefined number of records from your original data source.

Figure 1: Typical grid paging UI

Figure 2: Paging with a dropdown selector

Note: The grid’s Paging feature is implemented as a jQuery UI widget, and therefore follows the standard lifecycle typical of a jQuery UI widget.

Paging may be setup for local or remote execution. In the first case, the paging operations are performed on the client. This means that all your data is present in the browser, but only the number of records as specified by the pageSize property is rendered to the user.

In the case of the “remote” scenario, for every page change, the grid initiates a request to the dataSource specified in the grid, by automatically calculating and appending all necessary parameters to the request, such as pageIndex and pageSize.

The Paging feature allows the user to change the pageSize through the UI, which is available either in the grid header (above the grid column headers), or as part of the pager area.

Note: All parts of the paging UI can be navigated with keyboard using TAB and Shift-TAB.

Data Formats

The Paging feature supports binding to oData services out-of-the-box. When binding to oData, the required parameters are automatically determined and set in the service request. You only need to point the dataSource option of the grid to your service URL.

When using Paging from the Ignite UI for MVC, Grid all paging-related data binding logic is performed automatically by translating the paging URL parameters to LINQ expressions.

Depending on the value of the pageCountLimit property, the UI automatically switches from page links to rendering a page index dropdown.

Note: The dropdown & editors used in the grid’s Paging feature are instances of the igEditor control.

Enabling Paging

In order to enable Paging, you first need to include the necessary JavaScript and CSS dependencies. The easiest way to include the necessary dependencies is to use the combined/minified version of the scripts and styles as shown in Listing 1.

• Listing 1: Required script and CSS files for grid paging

  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.min.js"></script>
    <script type="text/javascript" src="jquery-ui.min.js"></script>
    <script type="text/javascript" src="infragistics.core.js"></script><script type="text/javascript" src="infragistics.lob.js"></script>
  

  If you would like to include only the minimal Ignite UI for jQuery™ scripts necessary for paging, you can do so by referencing the scripts as depicted in Listing 2.

• Listing 2: Minimum scripts and styles to enable grid paging

  In HTML:

    <script type="text/javascript" src="infragistics.util.js"></script>
    <script type="text/javascript" src="infragistics.util.jquery.js"></script>
    <script type="text/javascript" src="infragistics.dataSource.js"></script>
    <script type="text/javascript" src="infragistics.ui.shared.js"></script>
    <script type="text/javascript" src="infragistics.ui.popover.js"></script>
    <script type="text/javascript" src="infragistics.ui.editors.js"></script>
    <script type="text/javascript" src="infragistics.ui.grid.framework.js"></script>
    <script type="text/javascript" src="infragistics.ui.grid.paging.js"></script>
  

• Listing 3: Initializing the igGrid control with paging enabled

  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,
        responseDataKey: 'Records',
        features: [
            {
                name : 'Paging',
                type: "local",
                pageSize : 7
            }
        ]
    });
  

• Listing 4: HTML container used to instantiate the grid

  In HTML:

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

• Listing 5: Example JSON data

  Response:

    var adventureWorks = { "Records" : [ 
          { "Name" : "Adjustable Race",
            "ProductID" : 1,
            "ProductNumber" : "AR-5381"
          },
          { "Name" : "Bearing Ball",
            "ProductID" : 2,
            "ProductNumber" : "BA-8327"
          }
          /*the full JSON output is omitted*/
        ]
    }
  

Running sample

ASP.NET MVC Code

Listing 6 demonstrates how to initialize the Ignite UI for MVC Grid with paging enabled in an ASP.NET MVC view and controller.

• Listing 6: Initializing the grid with paging enabled in ASP.NET MVC

  In ASPX:

    <%= 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.Paging().PageSize(20);
       }).
       Height("500").
       DataSourceUrl(Url.Action("PagingGetData")).
       DataBind().
       Render() %>
  

  In C#:

    public class HomeController : Controller
    {
        public ActionResult Index()
        {
            return View();
        }
        [GridDataSourceAction]
        public ActionResult PagingGetData()
        {
            return View(this.GetCustomers().AsQueryable());
        }
        private List<Product> GetProducts()
        {
            List<Product> products = new List<Product>()
            {
                new Product() { ProductID = 1, Name = "Adjustable Race", ProductNumber = "AR-5381" },
                new Product() { ProductID = 1, Name = "Bearing Ball", ProductNumber = "BA-8327" }
            };
            return products;
        }
    }
  

Remote Paging

When you're using Ignite UI for MVC it will handle remote paging automatically for you. You are required to create action method decorated with GridDataSourceActionAttribute attribute which returns ActionResult (Listing 6). In the action method just pass the data as instance of IQueryable. The GridDataSourceActionAttribute class (which implements IActionFilter interface) will transform the data according the request parameters and will return it as JsonResult.

If you are implementing your own remote service (for example in ASP.NET or PHP), in order to properly initialize and render the pager, your service must specify both the responseDataKey (grid option) and the recordCountKey (paging option). The recordCountKey member tells the Paging widget how many records in total are in the backend. The responseDataKey specifies which property in the response contains the resulting data.

Therefore, when remote paging is used, the grid automatically generates the proper request parameters in the following way:

http://<server>/grid/PagingGetData?page=2&pageSize=25

Note: You may change the key names, by setting the pageSizeUrlKey / pageIndexUrlKey in the Paging options, respectively.

API Usage

You can change the page index or the page size programmatically, in the following ways:

• Listing 7: Retrieve the page size

  In Javascript:

    $(“#grid1”).igGridPaging("option", "pageSize");
  

• Listing 8: Retrieve the current page index

  In Javascript:

    $(“#grid1”).igGridPaging("option", "currentPageIndex");
  

• Listing 9: Change the current page index so that the third page is loaded

  In Javascript:

    $(“#grid1”).igGridPaging(“pageIndex”, 2);
  

You can easily achieve a “Quick Pages” effect in your grid, by changing the visiblePageCount option. This means that the grid only renders as many page links as defined by visiblePageCount. Therefore, if visiblePageCount is 5, and you are on page 3, page links “1” and “2” are rendered to the left, and page links “4” and “5” to the right.

Note: The Paging widget still renders a dropdown to choose the current page, if the actual page count exceeds the value of the pageCountLimit option.

You can also customize the page size list by setting the pageSizeList (array) option in the paging options. Each value in the array specifies the size of the page, added in order of page index. For instance:

pageSizeList: [10, 44, 123, 5]

The array above specifies a size for page 1 equal to 10 rows, 44 for page 2 and so on.

Client-Side Events

You can bind to client-side events either during initialization or after the widget is instantiated. The first approach allows you to existing instances of the grid:

• Listing 10: Associating event handlers to page indexed changed event on the client

  In Javascript:

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

Note: Use “live” instead of “bind” if paging is not yet instantiated.

The second approach allows you to define event handlers during initialization by specifying the event name as an option when you initialize the paging feature.

Note: This binding syntax is case sensitive as opposed to attaching with the bind or live jQuery functions.

• Listing 11: Associating event handler to page index changing during initialization

  In Javascript:

    {
        Name: “Paging”,
        pageIndexChanging: handler,
        < other paging options>
    }
  

Then your “handler” function would resemble the code in Listing 12.

• Listing 12: Blank event handler called by paging feature

  In Javascript:

    function handler(event, args) {
  
    }
  

Note: The args is explained in detail below, for every event, respectively.

Client Side Events

Table 1: List of Client-side Events

Location of Paging UI Elements

Figure 1: Location of paging UI elements

Known Issues and Limitations

• Selected cells and rows are not preserved across pages.

Paging Properties

Table 2 details the list of initialization options and descriptions available for the Paging feature.

Note: The value in parenthesis denotes the default option value.

Table 2: Available grid Paging initialization options

Paging CSS Classes

As you work with the grid Paging feature, you may want to customize the look of the pager for any given UI element. Table 3 details the available classes applied to the grid pager UI.

Table 3: Available classes for the Paging widget

Keyboard Interactions

The following keyboard interactions are available.

When focus is on the grid:

• TAB: Can move focus between the focusable elements of the pager UI: buttons, page links and drop-downs. When focus is on the page size drop-down the list of available page sizes will be displayed and the following interactions are available:
• UP/DOWN: To move between the available list items.
• SPACE/ENTER: To select the currently highlighted item. When a new item is selected the new page size is applied to the grid and the page size drop down closes.

When focus is on one of the pager buttons:

• ENTER/SPACE: Selects the active pager button and the current page index changes accordingly. When focus is on the page index drop down the list of available page indexes will be displayed and the same interactions as the page size drop-down apply for it.

Related Content

Topics

• igGrid Overview
• Selection Overview (igGrid)
• Filtering (igGrid)
• Sorting Overview (igGrid)