Migrating to Palomino: from C1WebGrid to C1GridView
Introduction
In recent months, you may have noticed some changes within the Studio for ASP.NET including the addition of new controls and utilities like Foxy for ASP.NET, our visual style designer for the ASP.NET controls. Some of these additions are entirely new concepts for the Studio for ASP.NET, while others have existing counterparts that they will be replacing. The C1GridView is a prime example of the latter, as it will be replacing the C1WebGrid in the months to come.
The C1GridView and our other new controls, collectively referred to as our Palomino controls, are fully AJAX-enabled and take advantage of many promising technologies like CSS, XHTML, and more. For many of you this may seem unsettling, especially those of you who have been using our ASP.NET controls for several years now; however, there is no need to fret as this article will walk you through the C1WebGrid to C1GridView migration.
Prerequisites
For this tutorial, you will need to download ComponentOne Studio for ASP.NET and the C1WebGrid sample application. A free 30-day full-featured trial and yearly subscriptions of ComponentOne Studio for ASP.NET are available from the ComponentOne website.
Getting Started
Open the sample application in Microsoft Visual Studio 2008, and add the necessary references to the sample by clicking by going to Project | Add Reference and browse to C:\Program Files\ComponentOne\Studio for ASP.NET\bin\. The following assemblies require project references:
- C1.Web.UI.3.dll
- C1.Web.UI.3.Controls.3.dll
* Please note that the assemblies may be located in the following file path: C:\Program Files\ComponentOne Studio.NET 2.0\ bin\. Also notice that there are two versions of the C1.Web.UI assemblies; one that targets the .NET Framework 2.0 and one that targets the .NET Framework 3.0.
Directly beneath the Page directive add the following directive for the C1GridView:
You should notice that C1GridView's directive is very similar to that of the C1WebGrid.
If you run the application at this point, you will see only the C1WebGrid; it should appear as follows:
Now let's migrate this C1WebGrid to the C1GridView.
Migrating C1WebGrid to C1GridView
First, switch to visual designer in Visual Studio and add an instance of the C1GridView to the page by selecting it from the Visual Studio Toolbox and dragging it to the page. Once the C1GridView has been added, open its smart tag (the arrow in the upper-right corner of the control) and from the Data Source drop down select AccessDataSource1 as shown below:
After selecting AccessDataSource1, the C1GridView will now appear as follows:
Before we continue any further, lets give the C1GridView a more appealing look for our users by leveraging the new VisualStyle property and one of the five styles included with the Studio for ASP.NET. To do this, open the C1GridView's smart tag and select Office2007Blue from the VisualStyle dropdown.
I would like to point out that the C1GridView automatically generates a checkbox column for Boolean columns, rather than just displaying true or false. With the C1WebGrid, this is certainly possible; however, this would require you, the developer, to manually set this up using a template column.
Now that we have given our users a more aesthetically appealing look, let's focus on the functionality that we will be providing to the users. The first item of business in terms of functionality is to allow our end-users to sort, move, and size columns along with enabling paging which can be done by changing the AllowColSizing, AllowColMoving, AllowSorting, and AllowPaging properties to True in the Visual Studio Properties menu. In addition to this, I would also suggest selecting the following C1GridView.CallbackOptions in the Properties menu:
Just like with the C1WebGrid, these changes will not have any real effect on the way the C1GridView is displayed to the end-user; however, changing these properties will greatly increase the usability of the control. If you run the application, you can see that columns in the C1GridView can be moved, sized, and sorted without requiring a full page refresh, and the same goes for paging. Now, let's move on to some of the finer modifications that will be necessary to recreate the existing C1WebGrid.
To make these finer modifications, it is not necessary to use code, though it can be done just as easily this way, but rather the C1GridView's Property Builder. To open the Property Builder, open the C1GridView's smart tag and select Property Builder; the following dialog box will appear.
From the dialog box, select the Show Filter checkbox under the Header and Footer portion of the menu, and then select Columns from the list of options on the left. Before moving on, I would like to mention that filtering is a built-in feature of the C1GridView control with plenty of options; this is a feature that you need to manually design and code for the C1WebGrid. Alternatively, changing the ShowFilter property to True in the Properties menu of Visual Studio would accomplish the same task.
Now in the Columns portion of the Property Builder, you will see the following:
The Selected Columns portion represents the columns that will appear in the C1GridView, while the Available Columns represent the columns and types of columns that you can add to the C1GridView like Image, Template, or Data columns. From the Selected Columns portion, click on CategoryName and change the RowMerge property to Free and the SortDirection property to Ascending; effectively, these changes will sort the CategoryName column alphabetically in ascending order while merging any repeating, like values into one "merged" cell as shown below.
Now from the Selected Columns in the Property Builder, select the ProductID column and set its SortDirection property to Ascending to sort this column alphabetically in ascending order. Afterwards, select the UnitPrice column and set its DataFormatString to {0:c} to format the column as a currency, rather than just displaying this column's value as an unformatted decimal value; you can manually type {0:c} in for the property or just select it from the dropdown.
Next, add a Band from the list of available columns to the selected columns and move the Band below the ProductName column by clicking the Move Column Up button in the Property Builder. After the Band has been moved to its proper place, select it and change its HeaderText property to Pricing and Availability. Afterwards, all that is left to do with the Band column is to move all columns below it into the Band column by clicking the Move Column Up button in the Property Builder. Once this is done, the Select Columns will look as follows:
Now select Delete from under the Command Field in Available Columns and add it the selected columns. After adding this, change its ShowDeleteButton to False and the ShowFilterButton to True; this will change this column from a delete column to the filter column. After this, change the ButtonType from Link to Image, then add the following to the FilterImageUrl property: ~/Images/filter.gif. This will make the column link for filtering to an image rather than a text link. Afterwards, run the application and your C1GridView should now look as follows:
Return to the C1GridView's Property Builder, but this time select Paging from the list of sections on the far left.
Once you are in the Paging section, change the mode from Numeric to NextPreviousFirstLast; the C1GridView will not display as follows, rather than using numbers to navigate through the data.
The last thing that needs to be done is adding a RowHeader, which is a new feature of the C1GridView. To do this, select the C1GridView and go to the Visual Studio Properties menu; locate RowHeader, expand it, and change its Visible property to True to display the RowHeader.
If you run the application now, the C1GridView is complete and should display as follows:
Feel free to take a few minutes at this point to use the C1GridView and try some of its new features like filtering and row selection using the row header.
Programming Considerations
Now as easy as this was, you may still be concerned about how things will be changing in terms of code, which is understandable. One of the major code changes in the C1GridView over the C1WebGrid is that the Items collection is now referred to as the Rows collection. So the C1WebGrid's ItemCreated event is now referred to as the RowCreated event in the C1GridView; the event still works the same way, but is just named differently. Let's make use of the C1GridView's RowDataBound event now to add a little bit more to the UnitsInStock column.
First, add an event handler for C1GridView's RowDataBound event. After you have done this, navigate to the code behind of your page and add the following using statement to the top:
using C1.Web.UI.Controls.C1GridView;
After this, locate the RowDataBound event and add the following code:
if (e.Row.RowType == C1.Web.UI.Controls.C1GridView.C1GridViewRowType.DataRow && e.Row != null)
{
e.Row.Cells[6].Text = string.Format("{0} Items", e.Row.Cells[6].Text);
}
This code snippet will make each cell under the UnitsInStock column display its value followed by "Items". At the end of this article, you can download the full list of differences between the C1WebGrid and the C1GridView.
Conclusion
Now that you have seen how to migrate a ComponentOne ASP.NET control to an updated Palomino control first hand, you can confidently supercharge your existing ASP.NET application by upgrading to C1GridView and the ComponentOne Studio for ASP.NET.
MESCIUS inc.