How to Use the Substitution Control

by Chris Love

ASP.NET 2.0 has many new features that I just love. There is a whole new set of great controls, including the Substitution Control. The basic definition of the Substitution control is a place on a page that is exempt from output caching. You now have the ability to exempt a portion of a page from being cached in memory, while making the remainder of the page cacheable. If you are wondering why you might want to do this; think advertising.

I really liked this control as soon as I figured out what it does. Now I can cache the pages of my site to make them load much faster, but yet control some content that still needs to be rendered dynamically. I am working a series of sites right now that run advertising campaigns; banners, contextual, AdSense, you name it we are running it. We want many of these ads to rotate around, that way we get even exposure for our advertisers. The Substitution control allows me to do this feat.

So let's take a look at some code. Here we see the Substitution control declared on our design surface:

<asp:Substitution ID='Substitution1' runat='server' MethodName='GetGoogle160x600Ad' />

Nothing fancy, the only other relevant parameter would be EnableViewState, so this is a pretty basic rendering control, sort of a modified literal. The new parameter to us is 'MethodName', it is used to define the name of the callback method that will be called at run-time. This method is defined in our page class and must be shared or static (for those C# folks). So let's take a look at this method:

Public Shared Function GetGoogle160x600Ad(ByVal context As HttpContext) As String

Return GetGoogleAd(160, 600, context)

End Function

What I have done is define a series of Messages to get the JavaScript code for rendering Google AdSense on the page. Essentially I have an overloaded routine here. I could set this anyway I wanted, so I could render any ad type on the fly. Since I need to specify the dimensions of the ad, so I can keep my layout looking good, I decided to setup a series of methods for each size of add that will then call the lower methods to get the correct code.

Now the Callback method must have a single parameter to receive the HttpContext. This is why I had to define a series of methods to define the dimension. The context is used by the control to get around the Page Caching directives and always generate fresh new content each time the page is loaded. This Callback method also must return a string. This string will be what is rendered in the control. So let me get you a little deeper, past several overload and refining methods and just go to the metal of it all.

Each method in your chain must be shared/static to be able to be used in the Callback. This is a common mistake when many programmers begin using shared methods, so here is your notice. This method has several parameters that will be used to define the actual code being rendered, like colors and dimensions. I have included some optional ones with some defaults, but this is not that important to the Substitution Control.

Private Shared Function GetGoogleAd(ByVal mHeight As Integer, ByVal mWidth As Integer, Optional ByVal BackColor As String = 'FFFFFF', Optional ByVal ForeColor As String = '000000') As String

Dim sb As New StringBuilder

sb.Append('<script type=''text/javascript''></script>' & vbLf)
        sb.Append('<script type=''text/javascript'' src=''http://pagead2.googlesyndication.com/pagead/show_ads.js''>' & vbLf)
        sb.Append('</script>' & vbLf)

Return sb.ToString

End Function

The method uses a StringBuilder to make the short JavaScript for Google's Adsense ad, at the end it is all spit out as a string and sent back up the chain to our Substitution Control.

This is a simple control to use on your pages. I think the biggest thing new developers and users of the control need to be aware of is the use of shared methods. Things work slightly different in these methods and you need to familiarize your self with them.