Grid and paging toolbar

gridex.gif

In order to add the grid with the paging toolbar to your views, two HtmlHelper calls are required. One for the grid, and another one for the pager toolbar, which is a separate component.

Grid

The grid syntax is exactly the same as the one of the original MvcContrib grid. For details please refer to the MvcContrib grid documentation. etcetera.Mvc uses 1.5.996.0 RC of MvcContrib due to its added column sorting syntax support.

The etcetera.Mvc grid just enhances the fluent interface of the grid:
<%= Html.GridEx<Actor>("Actors")
        .Titled("Actors")
        .WithToggle(true)
        .WithId("Act")
        .Columns(col =>
                     {
                         col.For(x => Html.ActionLink(x.Id.ToString(), "Actor", new { Id = x.Id })).DoNotEncode().Named("Id");
                         col.For(x => x.FirstName).Sortable(false);
                         col.For(x => x.LastName).Sortable(true);
                     })
%>

The following methods are specific to the etcetera.Mvc grid:
  • Titled(): If you call this method and specify a title, the grid will have a title bar with an optional toggle button.
  • WithToggle(): This allows you to optionally hide the toggle button. Per default the button is displayed. There's also an overload which allows you to show the grid collapsed when it is displayed initially. Toggling the grid requires JavaScript on the client side.
  • WithId: This applies an id parameter to the whole grid. This is required if you'd like to use the AJAX paging functionality.
  • SortQueryStringName() and SortOrderQueryStringName(): These two methods allow you to optionally define the query string parameter names for sorting grid columns. If omitted, the defaults "sort" and "order will be used.

Paging toolbar

The paging toolbar can be added to your views as follows. This renders a full blown paging toolbar with an additional "Add" and an "Export to Excel" button, as shown in the screenshot above:

<%= Html.PagerToolStrip("Actors")            
        .AjaxUrl(Url.Action("Actors", "Grid"))
        .AddToolbar(new Toolbar().AddButton("Add new Actor", Url.Action("New", "Grid"), "tBtnA"))
        .AddToolbar(new Toolbar().AddPageSizeSelect(10, 20, 50, 100))
        .AddToolbar(new Toolbar().AddNavButton(NavButton.First)
                                 .AddNavButton(NavButton.Previous))
        .AddToolbar(new Toolbar().AddPageInput())
        .AddToolbar(new Toolbar().AddNavButton(NavButton.Next)
                                 .AddNavButton(NavButton.Last))
        .AddToolbar(new Toolbar().AddPageStatus())
        .AddToolbar(new Toolbar().AddRefreshButton("Refresh Actors"))
        .AddToolbar(new Toolbar().AddButton("Export all Actors to Excel", Url.Action("ActorsExcel"), "tBtnXls"))
        .WithId("pgrC")
        .WithGridId("Act")
        .Format("Showing {0} to {1} of {2} actors")
        .SinglePageFormat("Showing {0} of {2} actors")
        .KeepPageSize()
        .ColModel(col =>
                    {
                        col.For("id", "Grid/Actor/{0}", "id");
                        col.For("firstname");
                        col.For("lastname");
                    })
%>

Each toolbar you add can contain any number of buttons or controls. There are a few predefined buttons and controls such as the navigation buttons, page size and page number input controls, refresh buttons, and the status text.
A toolbar is basically just a verically delimited area, so you can use different toolbars to group your buttons and controls as shown in the sample.

The paging toolbar need to know the grid ID. this is passed with the WithGridId() method.
The toolbar also needs to have an own ID, specify that using WithId(). Use different IDs if more than one grid/toolbar is used in the same view.

If you would like to add AJAX paging support to the grid and toolbar, you need to specify the controller action which returns a JsonResult. This is done via the AjaxUrl() method. If you omit this, paging the grid will reload the view.
The controller action signature needs to be defined as follows:
/// <summary>
/// Returns a paged JSON object with actors.
/// </summary>
/// <param name="p">The page number.</param>
/// <param name="ps">The page size.</param>
/// <param name="sort">The sort property name.</param>
/// <param name="order">The sort order.</param>
/// <returns></returns>
[AcceptVerbs(HttpVerbs.Get)]
public JsonResult Actors(int? p, int? ps, string sort, string order)


Of course you can choose any name for your action. The sample project in the etcetera.Mvc package shows a demo implementation of this controller action. Please refer to the GridController.cs sample.

The ColModel() let's you specify the format of the grid records returned by the controller's JsonResult. Specifing a fieldname for the column will just render the value of the according record field. Optionally you can also add an URL and a field of the JsonResult which will be applied to the URL.

A special option is the KeepPageSize(). This is only relevant if paging via AJAX is enabled. If the last page of the grid is shown, the grid will now adjust its height in case there are less rows than specified by the page size. Keeping the page size adds empty rows for the last page in this case.

The paging toolbar also knows the options SortQueryStringName() and SortOrderQueryStringName() as the grid. Additionally you can use PageQueryStringName() and PageSizeQueryStringName() to specify the query string parameter names for the page number and page size. the defaults are "page" and "pageSize".

Last edited Oct 15, 2009 at 1:16 PM by kherzam, version 3

Comments

No comments yet.