Steps for adding a CSS Control Adapter

I have had the chance to present the CSS Control Adapter Toolkit at several conferences and classes recently, and each time I present them they are very well received. People are pleased that it is possible to use the standard ASP.NET server controls but to be able to control their appearance entirely from CSS files. They also like the fact that many of the controls that render by default as HTML tables render with div and ul tags using the adapters.

I wrote an article on control adapters for MSDN Magazine back in October last year where I cover the mechanics of control adapters and how the CSS Control Adapter toolkit implements the changes they do. At the time, however, the toolkit was still in beta so the description at the end of the article on how to incorporate a particular adapter into an existing site is a bit out of synch with the release version. I promised several of the audiences I have presented to recently that I would blog about how to incorporate the adapters into your sites with the release bits, so here we go...

First of all, once you install the toolkit, you will have two new project types: ASP.NET CSS Friendly Web Site and Tutorial on ASP.NET CSS Friendly Control Adapters. I prefer to generate the tutorial and then pluck the pieces I need from the generated tutorial to my own project. The reason for this is that the tutorial contains samples of every control adapter while the 'CSS Friendly WebSite' is missing some samples (like the GridView). I also don't like starting with either of these site types when I create a new site because I rarely use all of the control adapters, and I prefer to pull each adapter in only as I need it in any given project. So in short:

Step 1: Generate a new Tutorial on ASP.NET CSS Friendly Control Adapters site

Step 2: Create your own standard ASP.NET site (or open an existing one) into which you will copy pieces of the ASP.NET CSS Friendly tutorial.

Step 3: Create a new App_Code directory in your site.

Step 4: Create a new App_Themes directory in your site with a subdirectory for a new theme (one that you will apply across the entire site) - for purposes of this walk-through we'll assume the theme subdirectory is named MyTheme.

Step 5: Create a new App_Browsers directory in your site.

Step 6: Create a new top-level CSS directory in your site.

Next I will walk through incorporating two different control adapters into your site, one that does not have any associated JavaScript (the GridView - a) and one that does (the Menu - b). The procedure for the other adapters will be essentially identical to one of these two.

Step 7a: Copy the GridViewAdapter.cs and WebControlAdapterExtender.cs (or .vb) files from the App_Code directory of the tutorial into your site's App_Code directory (note, if you add additional control adapters to your site you need only copy the WebControlAdapterExtender.cs file once).

Step 7b: For the menu control, you need to copy the MenuAdapter.cs (or .vb) file as well.

Step 8a: Copy the CSSFriendlyAdapters.browser file from the tutorial's App_Browsers directory to your site's App_Browsers directory.

Step 9a: Edit the CSSFriendlyAdapters.browser file to include only the GridViewAdapter (remove all the other registered adapters).

<controlAdapters>

<adapter controlType="System.Web.UI.WebControls.GridView"

adapterType="CSSFriendly.GridViewAdapter" />

</controlAdapters>

Step 9b: If you are adding the menu adapter, leave the MenuAdapter entry in there too:

<adapter controlType="System.Web.UI.WebControls.Menu"

adapterType="CSSFriendly.MenuAdapter" />

Step 10a: Copy the GridView.css file from the CSS directory in the tutorial into your local site's CSS directory.

Step 10b: If you are adding the menu adapter, also copy the Menu.css file in the same way.

Step 11a: Add a link to the GridView.css file to your master page(s). The simplest way to do this is to drag the .css file into the head element on your master page - it will auto-generate a proper stylesheet link.

Step 11b: For the Menu, add a link to Menu.css to your master page as well. If you find yourself using several control adapters, you may want to take the path that the tutorial does and create a single Import.css file that references all of the adapter stylesheet files. Then you only need to add a reference to Import.css to your master page.

Step 12a: Copy GridViewExample.css file from the App_Themes/Basic directory of the tutorial into your theme subdirectory. You may want to rename the file as well, perhaps to PrettyGridView.css since that is the name of the class it defines. This is the file you will make copies of to create different appearances for Grids in your site.

Step 12b: For the Menu, copy the MenuExample.css file as well as all of the image files (*.gif and *.png) from the App_Themes/Basic directory of the tutorial into your theme subdirectory. You may want to rename the .css file to PrettyMenu.css since that is the name of the class it defines.

Step 13a: Add a global theme reference to your web.config file to MyTheme (or whatever you named your theme).

<system.web>

<pages theme="MyTheme" />

…

Step 14a: Add the CssSelectorClass attribute to each grid in your site to tie it to the CSS class. Note that you will probably end up creating multiple classes, so this CssSelectorClass should point to the one you want that particular grid to use when it renders. Note you will not get intellisense when adding this property in Visual Studio.

<asp:GridView ID="_myGrid" runat="server" CssSelectorClass="PrettyGridView" ...

Step 14b: Add the CssSelectorClass attribute to each menu in your site to tie it to the CSS class.

<asp:Menu ID="_myMenu" runat="server" CssSelectorClass="PrettyMenu" …

Step 15a: That's it - try running your site, and all of your GridView controls should now render based on the class definition in the GridViewExample.css file. Note that if you want to exempt a particular GridView control from being rendered using the control adapter, you can set AdapterEnabled="false" on the grid and it will default to its traditional rendering.

Step 15b: We're not quite done with the Menu control yet as it has a JavaScript element to it as well. Create a new top-level /JavaScript directory in your site and copy the AdapterUtils.js and Menu.js files from the /JavaScript directory in the tutorial site to your site.

Step 16b: Now all of your menu controls should be rendered using the menu adapter! Note that if you don't want to place the helper JavaScript files in /JavaScript, you can change the location by adding an appSettings element for "CSSFriendly-JavaScript-Path" to specify another location:

<appSettings>

<add key="CSSFriendly-JavaScript-Path" value="~/MyScripts" />

</appSettings>

I hope this helps those of you trying to apply the CSS friendly control adapters to your sites!