Community Server on my mind

How to create a WeblogThemedControl

Want to create a Community Server control that adapts to your blog's theme/skin?

Community Server (CS) contains a class named WeblogThemedControl, which is used for many of the built in blog controls in CS. One of the features of the WeblogThemedControl is that it has a corresponding .ASCX file usually in the SKINS folder of your blog skin. This .ASCX file enables you to change the appearance of the control at runtime, without changing any of the WeblogThemedControl's source code. On top of that it adapts to the current skin of your blog.

There have been articles about the WeblogThemedControl before (i.e. Dan Bartel's "Creating a skinnable BlogStats web control for CS"), but I couldn't find any written this year, and no one as a sample in Visual Basic. This article's objective is also to be as generic as possible in the steps how to create such a control.

The .ASCX template file

First let's create the template file that will control the outcome of the control.

Figure 1: The .ASCX template

As you can see there is first a regular < h3 > header used as a title for the control outcome. Then, in this case, a regular ASP .NET Repeater control with a ItemTemplate. This can of course be any other ASP .NET control, like a Literal control used in Dan's example above. The Repeater's ID will be used later in the WeblogThemedControl to get a handle to the control.

Place the .ASCX file in the SKINS folder of your favorite CS blog skin. The file name for this .ASCX file should be Skin-[name of your WeblogThemedControl class].ASCX. Well, you haven't done any coding yet, so you probably don't know the class name yet. But you can go back and rename this file later when you have named your class.

The WeblogThemedControl source code

So, time to start coding the functionality of your control. Create a new Class Library in your Visual Studio, and then let's Inherit from WeblogThemedControl (which is a member of CommunityServer.Blogs.Controls).

Figure 2: Inheriting the WeblogThemedControl and overriding AttachChildControls

This might be a bit in the wrong order to be pedagogic, but in the picture above you also see that there is an override on the AttachChildControls method. I'll come back to that method later.

The first code you should concentrate on after inheriting the WeblogThemedControl is the override for the OnLoad event. In this case we just let the base class run it's OnLoad and then we issue an DataBind (in this case binding to our Repeater control that we put in the .ASCX file).

Figure 3: OverRide the OnLoad event

In the following example of an DataBind override, you can see a ThreadSet of blog posts being retrieved and being set as the DataSource for the topics object.

Figure 4: Override the DataBind method

If you now go back and look at Figure 2 above, your see that the topics object is a repeater. And in the override of the AttachChildControls method, we bind the topics object to the repeater we created earlier in the .ASCX file (see figure 1). Also in this particular case we add a eventhandler to the topics object to be able to do some work for each of the items that are going to be created in the repeater (the blog posts retrieve in Figure 4).

In the event handler we take care of each item coming into the repeater and determining how each one should look on the web page at runtime.

Figure 5: EventHandler for the items in the Repeater

In Figure 5 you can also see how we can get a handle to the < CS:Href -control that we put in the ItemTemplate of the Repeater in the .ASCX file.

So when you compiled the DLL, and put it in the BIN folder of your CS web, remember to go back to your .ASCX file and rename it to reflect the name of your class.

Then you'd want to put the control on your blog page. A good example would be to add it to the blog's sidebar (Skin-BlogSideBar.ascx). All you have to do there is to Register a TagPrefix for your Assembly, and then put a Tag for your control where you want it to appear.

In this article, I have tried to show you a way to use and create a CS WeblogThemedControl. Hopefully you are now a bit inspired to try some of your own ideas, on how you can show data from CS or any other source in a control that follows the looks of your blog, and can be edited (at least to some extent) without changing your source code.

[Update: added a Wikipedia link to the word pedagogic, after reading Dave's post /]