The Ultimate Cookbook for the ASP.NET MVC WebGrid

Most developers new to ASP.NET MVC think they need to use a table tag for their grid capabilities. Today, we cover a number of ASP.NET MVC WebGrid questions to create an ultimate WebGrid resource.

If you've been reading the site recently, you may have noticed I've provided a lot of WebGrid features in past posts for advanced users. Yet, I haven't discussed the basics of the WebGrid.

This post will be a post that will constantly be updated. It will contain the proverbial "cookbook" for developers looking for answers to WebGrid solutions. 

What is the namespace for an ASP.NET MVC WebGrid?

The WebGrid is located in the System.Web.Helpers namespace.

How do you create a WebGrid?

The simplest way to create a WebGrid is by defining it on your View and calling it from the View.

For example,

@using WebGridExample.Helpers.Html
@using WebGridExample.Models
@model IEnumerable<User>
@{
    var grid = new WebGrid(Model);
}
.
.
@MvcHtmlString.Create(
    grid.GetHtml().ToHtmlString()
)

The WebGrid has a huge number of parameters to pass into the constructor.

For the method GetHtml(), there are a ton of parameters for that as well.

I will be covering a number of these parameters, but not all of them. If you want to examine them further, please refer to the MSDN WebGrid docs.

How do you add attributes to a WebGrid?

The best way to add your styles to the WebGrid is to use the htmlAttributes parameter.

@MvcHtmlString.Create(
    grid.GetHtml(
        htmlAttributes: new {
            id = "grid",
            @class = "table table-bordered table-striped table-condensed"
        }
    ).ToHtmlString()
)

However, for the class attribute, you can remove the @class line and move the classes into the tableStyle property.

@MvcHtmlString.Create(
    grid.GetHtml(
        tableStyle: "table table-bordered table-striped table-condensed",
        htmlAttributes: new {
            id = "grid"
        }
    ).ToHtmlString()
)

How do you build WebGrid columns?

The parameters passed into a WebGrid can get lengthy. Pass in the columns using the columns parameter and use the WebGrid's Columns method to define your list of WebGridColumn. 

@MvcHtmlString.Create(
    grid.GetHtml(
        tableStyle: "table table-bordered table-striped table-condensed",
        htmlAttributes: new {
            id = "grid"
        },
        columns: grid.Columns(
            grid.Column("UserName" , "User Name"),
            grid.Column("FirstName", "First Name"),
            grid.Column("LastName" ,"Last Name"),
            grid.Column("LastLogin", "LastLogin")
        )
    ).ToHtmlString()
)

The first parameter in the Column constructor is the column name and the second parameter is the heading.

Ok, how do you build custom columns?

As I've mentioned before, you don't want to add a ton of code into your views, but you need to render custom data somehow.

By using HtmlHelpers.

In one example of the WebGrid series, I added an Options column for record specific functions and used an HtmlHelper by passing in the User object.

@MvcHtmlString.Create(
    grid.GetHtml(
        tableStyle: "table table-bordered table-striped table-condensed",
        htmlAttributes: new {
            id = "grid"
        },
        columns: grid.Columns(
            grid.Column("UserName" , "User Name", canSort: false),
            grid.Column("FirstName", "First Name"),
            grid.Column("LastName" ,"Last Name"),
            grid.Column("Full Name", format: @<text>item.FirstName+" "+item.LastName</text>),
            grid.Column("LastLogin", format: item => item.LastLogin.ToString("d")),
            grid.Column("Options", format: item => 
                Html.DisplayRecordOptions(item.Value as User), canSort: false)
        )
    ).ToHtmlString()
)

When using custom columns, you want to use the format parameter to make your custom column data. Depending on your ViewModel, you could very easily create an HtmlHelper to display anything you wanted in a column (i.e. image, buttons, PDF, etc).

Of course, you don't want the column sorted either, so you can turn sorting off using the canSort property.

Notice the @<text></text> tags? Anything inside of text will be taken literally. So in the FullName column, you'll see:

item.FirstName+" "+item.LastName

As you can see, I included a number of examples of how to format your columns.

If you want an example of the DisplayRecordOptions HtmlHelper, I'll refer you to the ASP.NET MVC: Enhancing the WebGrid - Inline Editing using SignalR post.

If you need a refresher on how to create an HtmlHelper, refer to the ASP.NET MVC HtmlHelpers: Clean up Your Views With HtmlHelpers post.

How can I apply paging to WebGrid?

Paging is defined through the WebGrid constructor.

@{
    var grid = new WebGrid(Model, canPage: true, rowsPerPage: 20);
}

It provides the basic paging mechanism, but I would refrain from using it because it provides paging at the client level as opposed to the server side/database level of paging.

You want the minimal amount of data returned to display a complete View.

If you want to modify the text on the paging, add the First, Previous, Next, and Last properties with the text for each appropriate function.

@MvcHtmlString.Create(
    grid.GetHtml(
        tableStyle: "table table-bordered table-striped table-condensed",
        mode: WebGridPagerModes.All,
        firstText: "First",
        previousText: "Prev",
        nextText: "Next",
        lastText: "Last",
        htmlAttributes: new {
            id = "grid"
        },
        columns: grid.Columns(
            grid.Column("UserName" , "User Name", canSort: false),
            grid.Column("FirstName", "First Name"),
            grid.Column("LastName" ,"Last Name"),
            grid.Column("LastLogin", format: item => item.LastLogin.ToString("d")),
            grid.Column("Options", format: item => 
                Html.DisplayRecordOptions(item.Value as User), canSort: false)
        )
    ).ToHtmlString()
)

How do I sort a WebGrid?

By default, a WebGrid defines every column as sortable.

To turn off sorting at the column level, pass in canSort: false (in bold).

@MvcHtmlString.Create(
    grid.GetHtml(
        tableStyle: "table table-bordered table-striped table-condensed",
        htmlAttributes: new {
            id = "grid"
        },
        columns: grid.Columns(
            grid.Column("UserName" , "User Name", canSort: false),
            grid.Column("FirstName", "First Name"),
            grid.Column("LastName" ,"Last Name"),
            grid.Column("LastLogin", "Last Login"),
            grid.Column("Options", format: item => 
                Html.DisplayRecordOptions(item.Value as User), canSort: false)
        )
    ).ToHtmlString()
)

How can I nest another WebGrid inside another WebGrid?

Remember when I said you can build anything into a WebGrid Column?

If each user belonged to a group, you could add a column displaying their groups in a table.

Here is the nested WebGrid:

@MvcHtmlString.Create(
    grid.GetHtml(
        tableStyle: "table table-bordered table-striped table-condensed",
        htmlAttributes: new {
            id = "grid"
        },
        columns: grid.Columns(
            grid.Column("UserName" , "User Name", canSort: false),
            grid.Column("FirstName", "First Name"),
            grid.Column("LastName" ,"Last Name"),
            grid.Column("LastLogin", "Last Login"),
            grid.Column("SubGrid", format: (item) =>
            {
                var subGrid = new WebGrid((item.Value as User).Groups);
                return subGrid.GetHtml(
                    tableStyle: "table table-bordered table-condensed",
                    htmlAttributes: new { id="subGrid"},
                    columns: subGrid.Columns(
                        subGrid.Column("Groups", 
                            format: (groupString) => groupString, 
                            canSort: false)
                    )
                );
            }, canSort: false)
        )
    ).ToHtmlString()
)

How can I use AJAX/SignalR with a WebGrid?

If you want a modern web application, learning Ajax and SignalR should be one of your top priorities. SignalR is one of my favorite libraries for performing real-time transactions over the web.

Instead of going over a huge post of how to integrate Ajax or SignalR into your WebGrid, I will refer you to some techniques I covered in my WebGrid Series:

• ASP.NET MVC: Enhancing the WebGrid - Lazy Loading with WebAPI
• ASP.NET MVC: Enhancing the WebGrid - Lazy Loading with SignalR
• ASP.NET MVC: Enhancing the WebGrid - Inline Editing with SignalR

Conclusion

This post will be a living, breathing, document as I continue to use the WebGrid throughout my travels. I will always be expanding this post because of ASP.NET MVC 6 arriving soon.

If anyone is looking for a specific WebGrid topic or technique, please let me know or post a comment below.