In the presentation I covered basic grid usage, auto-generated columns, paging, sorting and extensibility using custom grid renderers.

The sample code that I used in the presentation is available here. The video for the talk is available on viddler.

• Part 1 – Introduction
• Part 2 – New Syntax
• Part 3 – GridModels and GridRenderes
• Part 4 – Limitations of the WebFormsViewEngine
• Part 5 – The Action Syntax
• Part 6 – Sorting
• Part 7 – Auto-generated columns

The MvcContrib grid provides a way to automatically generate columns based on the public properties of an object. This is particularly useful when you are using a dedicated presentation model where the object properties map directly to the columns that you want to display.

To make use of this feature, you can call the AutoGenerateColumns method in the Grid declaration:

<%= Html.Grid(Model).AutoGenerateColumns() %>

By default, this will generate one column per public property and the name of the property will be used as the column heading (although PascalCased properties will have spaces inserted, eg “DateOfBirth” would be rendered as “Date Of Birth”).

This output can be customised by making use of MVC2’s ModelMetadata.

Out of the box, MVC2 uses the System.ComponentModel.DataAnnotations attributes to obtain metadata about a particular type (although you can also use other frameworks). The following attributes can be used to customise the auto-generated columns:

• ScaffoldColumn – can be used to prevent a property from being rendered as a grid column
• DisplayName – can be used to provide a custom column heading
• DisplayFormat – can be used to specify a custom display format

Additional columns not on your presentation model can also be added by making a call to the normal Columns method after the call to AutoGenerateColumns. For example, imagine we have a CustomerPresentationModel:

public class CustomerPresentationModel {
 
   [ScaffoldColumn(false)]
   public int CustomerId { get; set; }
 
   public string Name { get; set; }
   public DateTime DateOfBirth { get; set; }
}

If a collection of these objects is passed to the Grid method, then two columns will be auto-generated – one for Name and one for DateOfBirth (CustomerId is excluded because it is decorated with ScaffoldColumn(false))

If we also want to add an “Edit” link for the customer, then we could add an additional column:

<%= Html.Grid(Model).AutoGenerateColumns().Columns(extraColumns => {
        extraColumns.For(x => Html.ActionLink("Edit Customer", "Edit", new{ id = x.CustomerId });
}) %>

The additional column contains a link to the edit page for each customer. Note that while columns are automatically HTML-encoded, the grid will detect that ActionLink returns an instance of MvcHtmlString and therefore won’t encode this particular column.

Additional columns can also be re-ordered. For example, if we wanted our “Edit” link to appear before the Name/DateOfBirth then the InsertAt method could be used:

<%= Html.Grid(Model).AutoGenerateColumns().Columns(extraColumns => {
        extraColumns.For(x => Html.ActionLink("Edit Customer", "Edit", new{ id = x.CustomerId })
            .InsertAt(0);
}) %>

Note that the InsertAt method is not contained in the latest MvcContrib release – you’ll need to build from source to get this.

I’ve also started to put together some documentation for the grid on the MvcContrib wiki.

• Part 1 – Introduction
• Part 2 – New Syntax
• Part 3 – GridModels and GridRenderes
• Part 4 – Limitations of the WebFormsViewEngine
• Part 5 – The Action Syntax
• Part 6 – Sorting
• Part 7 – Auto-generated columns

I recently added single-column sorting support to the MvcContrib grid. This can be turned on by calling the “Sort” method on a grid declaration and accepting a parameter of type GridSortOptions in your controller actions.

Controller:

public ActionResult Sorting(GridSortOptions sort) 
{
  ViewData["sort"] = sort;
  var people = _peopleFactory.CreatePeople();
 
  if(!string.IsNullOrEmpty(sort.Column)) {
    people = people.OrderBy(sort.Column, sort.Direction);
  }
 
  return View(people);
}

View:

<%= Html.Grid(Model)
  .Sort(ViewData["sort"] as GridSortOptions)
  .Columns(column => {
      column.For(x => x.Id).Named("Person ID");
      column.For(x => x.Name);
      column.For(x => x.Gender);
      column.For(x => x.DateOfBirth).Format("{0:d}");
    }) %>

By calling the “Sort” method, this tells the grid that sorting should be enabled. This will generate sorting links for each column heading (note that currently sorting is enabled for all columns – there is no way to enable it for individual columns only. I’ll change this in a future release)

These sorting links will add two additional parameters to the querystring: Column and Direction. These can be handled in your controller action by taking as a parameter an object of type GridSortOptions.

Using this object, you can then sort your data using whatever mechanism you choose. Out of the box, MvcContrib provides an overload for the “OrderBy” extension method that takes a property name and a direction and delegates the sorting to IQueryable. However, use of this extension method is entirely optional.

This also works with the grid’s paging support, so if you want your data to be both paged and sorted then you can make a call to AsPagination (or by using a custom IPagination provider) after the call to OrderBy:

public ActionResult SortingAndPaging(int? page, GridSortOptions sort) 
{
  ViewData["sort"] = sort;
  var people = _peopleFactory.CreatePeople();
 
  if (!string.IsNullOrEmpty(sort.Column)) {
    people = people.OrderBy(sort.Column, sort.Direction);
  }
 
  people = people.AsPagination(page ?? 1, 10);
 
  return View(people);
}

…and the results will be as expected.

When a column is sorted, the CSS classes of “sort_asc” or “sort_desc” will be applied to the relevant <th> element, so you can style the column headings (for example, by adding up/down arrows).

I demonstrated the use of FluentHtml (with behaviours), the Grid and Pager components, the ActionResult assertions and the route testing extensions.

Slides and code can be downloaded here.

I’ve also put together a guide to contributing to MvcContrib using git for those without git experience.

• Part 1 – Introduction
• Part 2 – New Syntax
• Part 3 – GridModels and GridRenderes
• Part 4 – Limitations of the WebFormsViewEngine
• Part 5 – The Action Syntax
• Part 6 – Sorting
• Part 7 – Auto-generated columns

The rewritten MvcContrib grid now has an alternative syntax thanks to the work of Will Shaver. This syntax is called the ‘Action’ syntax as it makes heavy use of the System.Action delegate.

Enabling the ActionSyntax

By default, the methods associated with the Action Syntax will not show up as they are extension methods that live in a different namespace to the rest of the grid. Out of the box only the default syntax will work. To enable the Action Syntax you’ll need to either import the MvcContrib.UI.Grid.ActionSyntax namespace either in your .aspx view…

<%@ Import Namespace="MvcContrib.UI.Grid.ActionSyntax" %>

…or in your web.config’s namespace import section:

<system.web>
  <pages>
    <namespaces>
        <add namespace="MvcContrib.UI.Grid.ActionSyntax" />
    </namespaces>
  </pages>
</system.web>

Comparing the two syntaxes

There are several differences between the two syntaxes. Here is a grid definition using the default syntax:

<%= Html.Grid(Model)
	.Columns(column => {
  		column.For(x => x.Id).Named("Person ID");
     		column.For(x => x.Name);
     		column.For(x => x.Gender);    
     		column.For(x => x.DateOfBirth).Format("{0:d}");
		column.For("View Person").Named("").Partial("ViewPersonPartial"); //Example of using a Partial view for complex cells
     	}).RowStart(row => string.Format("<tr{0}>", row.IsAlternate ? "style=\"background-color:#CCDDCC\"" : "")) 
  %>

Here we’re specifying that the View Person column is a custom column that should be rendered using a Partial View, and the start of every alternate row has a background colour**.

Here is the same grid defined using the ActionSyntax:

<% Html.Grid(Model).Columns(column => {
     		column.For(x => x.Id).Named("Person ID");
     		column.For(x => x.Name);
     		column.For(x => x.Gender);
     		column.For(x => x.DateOfBirth);
                column.For("View Person").Named("").Action(p =>	{ %>
                     <td style="font-weight:bold">
	                <%= Html.ActionLink("View Person", "Show", new { id = p.Id })%>
	             </td>
                <% });
     	}).RowStart((p,row)  => {     
             if (row.IsAlternate) { %>
                   <tr style="background-color:#CCDDCC">
             <%  }  else  { %>
                 <tr>
             <% }
    }).Render(); %>

Note the following differences:

• The ActionSyntax requires the use of <% %> tags rather than <%= %> tags.
• The ActionSyntax requires that you end your grid definition with a call to the Render method or the grid will not show up if you do not call Render.
• You must terminate the call to Render with a semicolon
• You can directly embed HTML in the grid definition rather than using strings or partial views

Both syntaxes have their advantages and disadvantages but the end result is the same. You’re free to use whichever one you prefer.

**Both the partial view/actionsyntax approach are designed only for complex column definitions. This example was quite contrived and you could achieve the same result with a far simpler approach:

<style type="text/css">
.gridrow_alternate { background-color:#CCDDCC; }
</style>
<%= Html.Grid(Model)
	.Columns(column => {
  		column.For(x => x.Id).Named("Person ID");
     		column.For(x => x.Name);
     		column.For(x => x.Gender);    
     		column.For(x => x.DateOfBirth).Format("{0:d}");
		column.For(x => Html.ActionLink("View Person", "Show", new { id = p.Id }))
                           .Attributes(x => new Hash(style => "font-weight:bold"));
     	}) %>

• Part 1 – Introduction
• Part 2 – New Syntax
• Part 3 – GridModels and GridRenderes
• Part 4 – Limitations of the WebFormsViewEngine
• Part 5 – The Action Syntax
• Part 6 – Sorting
• Part 7 – Auto-generated columns

I was recently asked a question by one of the other MvcContrib comitters, Will Shaver, about why the ToString method of the Grid does not return the HTML for the grid, but instead writes the html its internal textwriter and then returns null.

This is the offending piece of code:

public override string ToString() 
{
	_gridModel.Renderer.Render(_gridModel, DataSource, _writer, context);
	return null;
}

This means that when ToString is called on the grid the GridRenderer will render the appropriate HTML to a textwriter (which is actually the HTTP Response output stream). From the end user’s perspective, this shouldn’t make a difference because it ‘appears’ that the grid is being rendered at the correct location:

<%= Html.Grid(Model.People).Columns(...) %>

ToString is implicitly called at the end of the <%= %> block which causes the rendering to occur.

What a silly way to create some html!

Yes, it may seem like a strange way of doing things but there is actually a good reason for this. In order to support rendering Partials for parts of the grid it is necessary that the grid is written directly to the response stream due to limitations of the WebForms View Engine.

What about passing a custom TextWriter to IView.Render?

The ASP.NET MVC IView represents the view that will be rendered. Take a look at the signature for its Render method:

void Render(ViewContext viewContext, TextWriter writer);

You might think that it would be possible to pass a StringWriter to the Render method, capture the output of the partial view and then store it internally in the grid. Unfortunately, this isn’t possible. I’m guessing the TextWriter parameter here is a hook for a future extensibility point – the current implementation of WebFormView completely ignores the parameter. In fact, internally WebFormView has to make use of HttpContext.Current in order to work around the limitation of .aspx/web forms.

What about the BlockRenderer?

MvcContrib contains a class called the BlockRenderer that can be used to capture the outputs of a view by making use of a Response Filter. While I could have used this approach, it suffers from several major flaws. In order for this approach to work, it is necessary to Flush the response stream before inserting the CapturingResponseFilter. This causes problems if you’re trying to do anything funky with HTTP Headers, or even something as simple as trying to set the Content Type. Check out this post on the MVC Forums for more details. There are other hacks that can be used, but none of them are ideal

In the end I decided the least evil approach was to render to Response.Output from within ToString as it causes the fewest problems for the end user. Hopefully with the release of ASP.NET 4.0 the MVC Team will be allowed to make some changes to the underlying WebForms engine in order to make it possible to capture view output.

• Part 1 – Introduction
• Part 2 – New Syntax
• Part 3 – GridModels and GridRenderes
• Part 4 – Limitations of the WebFormsViewEngine
• Part 5 – The Action Syntax
• Part 6 – Sorting
• Part 7 – Auto-generated columns

Internally, the new MvcContrib grid makes use of the GridModel and GridRenderer classes to create the grid definition and then render it. It is possible to make use of these classes yourself to customise the grid.

Grid Models

The GridModel stores the definition for the grid. That is, it contains column definitions, custom attributes and the renderer to use (see below). Each time you call a method on the Grid class it is delegated to the underlying GridModel. For example, calling the Columns defines a collection of GridColumn objects which are instantiated and stored in the GridModel:

<%= Html.Grid(Model.People).Columns(column => {
               column => column.For(x => x.Name);
               column => column.For(x => x.DateOfBirth);
}) %>

Instead of defining columns in your view, you can create your own GridModel and then pass this object to a call to Html.Grid:

public class PersonGridModel : GridModel<Person> {
    public PersonGridModel() {
        Column.For(x => x.Name);
        Column.For(x => x.DateOfBirth);
    }
}

<%= Html.Grid(Model.People).WithModel(new PersonGridModel()) %>

Note that GridModels aren’t limited just to column definitions. Everything that you could invoke by calling Html.Grid has an equivalent method on the GridModel (eg setting Empty Text, custom section overrides, header attributes etc).

There are several advantages of this approach:

• If you have large grid definitions using a GridModel can help to keep the view uncluttered.
• It is easy to re-use the same grid in multiple locations.
• You can re-use common grid code through inheritance.

There is one other benefit to using a GridModel. Visual Basic 2008 doesn’t support Lambda Statements meaning that it is not possible to use the Columns() method on the Grid directly. By using a grid model then you can still make use of the grid from within VB (if you’re that way inclined).

Grid Renderers

Internally, it is the job of the GridRenderer to take a GridModel and render it to the output stream. The default GridRenderer is the HtmlTableGridRenderer. Which, surprisingly enough, renders the grid as an HTML table. By specifying your own GridRenderer, you can completely alter how the grid is rendered without resorting to completely rewriting the grid component.

For example, in one of my larger ASP.NET MVC applications I frequently have the need to output data as an Excel spreadsheet and I used the grid to do so. In order to make this work I had to inherit from GridBase and override the methods related to generating output and then define a new set of helper methods to cater for the various Grid overloads. In the end I ended up with several overloads like this:

public static void ExcelGrid<T>(this HtmlHelper helper, string viewDataKey, Action<IRootGridColumnBuilder<T>> columns) where T : class
public static void ExcelGrid<T>(this HtmlHelper helper, string viewDataKey, Action<IRootGridColumnBuilder<T>> columns, Action<IGridSections<T>> sections) where T : class
public static void ExcelGrid<T>(this HtmlHelper helper, string viewDataKey, IDictionary htmlAttributes, Action<IRootGridColumnBuilder<T>> columns) where T : class 
public static void ExcelGrid<T>(this HtmlHelper helper, string viewDataKey, IDictionary htmlAttributes, Action<IRootGridColumnBuilder<T>> columns, Action<IGridSections<T>> sections) where T : class
public static void ExcelGrid<T>(this HtmlHelper helper, IEnumerable<T> dataSource, Action<IRootGridColumnBuilder<T>> columns) where T : class
public static void ExcelGrid<T>(this HtmlHelper helper, IEnumerable<T> dataSource, Action<IRootGridColumnBuilder<T>> columns, Action<IGridSections<T>> sections) where T : class 
public static void ExcelGrid<T>(this HtmlHelper helper, IEnumerable<T> dataSource, IDictionary htmlAttributes, Action<IRootGridColumnBuilder<T>> columns) where T : class 
public static void ExcelGrid<T>(this HtmlHelper helper, IEnumerable<T> dataSource, IDictionary htmlAttributes, Action<IRootGridColumnBuilder<T>> columns, Action<IGridSections<T>> sections) where T : class

…which was largely a duplication of the Grid overloads in mvccontrib. They could then be used like this:

<% Html.ExcelGrid(Model.People, column => {
         column.For(x => x.Name);
         column.For(x => x.DateOfBirth);
 }); %>

…which would produce the grid as Excel-XML.

With the new grid I can create a new GridRenderer implementation and then use it like this, with no need to create additional HtmlHelper extensions:

<%= Html.Grid(Model.People).Column(column => {
               column => column.For(x => x.Name);
               column => column.For(x => x.DateOfBirth);
}).RenderUsing(new ExcelGridRenderer<Person>());

The ExcelGridRenderer could inherit from GridRenderer and override the methods needed for constructing the grid header, footer, rows etc. You may notice that the methods on GridRenderer are very similar to those on the GridBase class. This is not a coincidence – most of the code in the GridRenderer is re-used from the old GridBase.

Note it is also possible to specify the renderer from within a GridModel:

public class PersonGridModel : GridModel<Person> {
    public PersonGridModel() {
        Column.For(x => x.Name);
        Column.For(x => x.DateOfBirth);
        RenderUsing(new ExcelGridRenderer<Person>());
    }
}

Hopefully this brief introduction to GridRenderers and GridModels shows how it is possible to make your grids extendable and reusable. In my next post I’m going to focus on Paging in more detail. My next post covers working around some of the issues of the WebForms View Engine.

• Part 1 – Introduction
• Part 2 – New Syntax
• Part 3 – GridModels and GridRenderes
• Part 4 – Limitations of the WebFormsViewEngine
• Part 5 – The Action Syntax
• Part 6 – Sorting
• Part 7 – Auto-generated columns

Edit: 28 Feb 09 I have removed the use of Partial views in the latest MvcContrib trunk for certain areas where it didn’t really make sense. The examples below have been updated to reflect this.

The updated version of the MvcContrib grid has a new syntax that uses method chaining and lambda expressions to build a fluent interface. Here is a grid defined with the new syntax:

<%= Html.Grid(Model.People).Columns(column => {
     		column.For(x => x.Id).Named("Person ID");
     		column.For(x => x.Name);
     		column.For(x => x.DateOfBirth).Format("{0:d}");
     	})
        .Attributes(style => "width:100%")
     	.Empty("There are no people.")
     	.RowStart(row => "<tr foo='bar'>") %>

Compare this to the same grid defined using the old syntax:

<%
  Html.Grid(Model.People,
    new Hash(empty => "There are no people", style => "width:100%"),
    column => {
	column.For(x => x.Id, "Person Id");
     	column.For(x => x.Name);
     	column.For(x => x.DateOfBirth).Format("{0:d}");
    }, sections => {
       sections.RowStart(item => { %>
          <tr> <!-- some custom html for the row start here -->
   <% });
%>

Note how grid options (eg Empty) are now specified as part of the fluent interface rather than part of the HTML Attributes dictionary (which I always felt was messy). The use of method chaining also means that it is no longer possible to embed html blocks inside the grid definition (eg RowStart). However, you can still achieve the same functionality using the RowStart method and specifying specifying a lambda that will return the HTML string to output.

The column definitions are almost identical identical.

Paging support

Unlike its predecessor, the new grid does not have any logic for dealing with paging. This has all been moved to a separate Pager component. The old grid rendered the pager in its footer, while with the new grid you’d need to write your page like this:

<%= Html.Grid(Model.People).Columns(column => {
     		column.For(x => x.Id).Named("Person ID");
     		column.For(x => x.Name);
     		column.For(x => x.DateOfBirth).Format("{0:d}");
}) %>
 
<%= Html.Pager(Model.People) %>

Where’s the code?

The code for the new grid is not in the mvccontrib release, so if you want to play with it you’ll need to download and build the source. Alternatively, I’ve put together a custom build that can be downloaded here for the subversion-impaired.

In my next post, I’ll be focussing on extending the grid by using GridModels and GridRenderers.