This is a post in my blog series Introduction to Chameleon...
Chameleon includes a set of utility controls to help theme developers implement custom themes. In this post, I'll list and describe some of these utility controls.
Some of the more notable utility controls include:
- ConditionalAction (<CSControl:ConditionalAction />)
The ConditionalAction control simply combines the decision-making abilities of Condition controls with behaviors implemented by Action controls. It contains two inner-properties: Conditions and Actions. When Conditions evaluates to true, the Actions are executed.
As an example,
<CSControl:ConditionalAction runat="server">
<Conditions>
<CSControl:UserPropertyValueComparison runat="server" ComparisonProperty="IsAnonymous" Operator="IsSetOrTrue" />
</Conditions>
<Actions>
<CSControl:GoToSiteUrlAction runat="server" UrlName="login_clean" />
</Actions>
</CSControl:ConditionalAction>
would redirect users who were not logged in (anonymous users) to the login page.
- ConditionalContent (<CSControl:ConditionalContent />)
The ConditionalContent control works like an IF-ELSE statement for content. Along with the basic single value control properties, it exposes a ContentCondition inner-property with which any conditions controls can be used. If the ContentCondition evaluates to true, the content of the TrueContentTemplate is rendered, otherwise the FalseContentTemplate is rendered. For example,
<CSControl:ConditionalContent runat="server">
<ContentConditions><CSControl:QueryStringPropertyValueComparison QueryStringProperty="condition" Operator="EqualTo" ComparisonValue="true" runat="server" /></ContentConditions>
<TrueContentTemplate>It's true!</TrueContentTemplate>
<FalseContentTemplate>It's false!</FalseContentTemplate>
</CSControl:ConditionalContent>
would render "It's True!" if the querystring contained "condition=true" and "It's False!" otherwise.
- ModifiedUrl (<CSControl:ModifiedUrl />)
The ModifiedUrl control will link its content to a modified version of the current URL. Beyond the basic single value control properties, it adds support for specifying modifications to the querystring (QueryStringModification) and target (TargetLocationModification) of the linked URL.
- PlaceHolder (<CSControl:PlaceHolder />)
The PlaceHolder control works similarly to the ASP.net PlaceHolder control--in that it contains other controls and has no default rendered markup--but adds the common Chameleon properties for single value controls.
PlaceHolder controls are useful when DisplayConditions need to be applied to non-Chameleon controls or when many Chameleon controls will be affected by the same DisplayConditions. Wrapping any number or type of controls within a PlaceHolder control and defining its DisplayConditions will ensure that all of the controls in its ContentTemplate will be rendered or left unrendered appropriately.
- ThemeImage (<CSControl:ThemeImage />, <CSBlog:ThemeImage />)
The ThemeImage controls work the same as ASP.net Image controls except that they interpret the leading "~" in the ImageUrl and DescriptionUrl properties as being the root of the theme instead of the root of the application. The <CSControl:ThemeImage /> control interprets "~" as the site theme's root whereas the <CSBlog:ThemeImage /> control interprets "~" as the blog theme's root.
The ThemeImage controls are a theme developers best friend when images need to be included in a custom theme.
- ThemeScript (<CSControl:ThemeScript />, <CSBlog: ThemeScript />)
The ThemeScript controls do for script inclusions what the ThemeImage controls do for image inclusions--they render the <script type="text/javascript" src="..."></script> mark-up for the given Src URL, interpreting "~" as the site or blog theme's root.
- ThemeStyle (<CSControl:ThemeStyle />, <CSBlog:ThemeStyle />)
The ThemeStyle controls do for stylesheet inclusions what the ThemeImage controls do for image inclusions--they render the <link rel="stylesheet" href="..." /> mark-up for the given Href URL, interpreting "~" as the site or blog theme's root.
- SiteUrl (<CSControl:SiteUrl />)
The SiteUrl control provides the basic single value control properties, along with properties to link its content to a given site url (as defined in siteurls.config). The control supports specifying the site url name (UrlName), parameters (Parameter1 to Parameter9), query string modifications (UrlQueryStringModifications) and target modifications (UrlTargetLocationModification).
The SiteUrl control is useful when static or data-less links are required in a theme.
- CSThemePage
CSThemePage (including application-specific overrides) is used as the page class for all pages in Chameleon themes. Pages based on CSThemePage include utility properties and methods for retrieving information from the current page's context, such as CurrentCSContext, CurrentPost, CurrentSection, CurrentGroup, etc and setting the page title.
Other Chameleon controls use CSThemePages implicitly, but the properties and methods defined on CSThemePage can also be utilized by theme developers. For example, on a file gallery page (using CSFileThemePage),
<script language="C#" runat="server">
void Page_Load()
{
if (CurrentEntry != null)
SetTitle(CurrentEntry.Subject, true);
}
</script>
sets the page title to the current entry's subject if a current entry exists. The CurrentEntry property and SetTitle method are both defined on the CSFileThemePage.
Note that the properties and methods exposed by CSThemePage are generally used via code and not by use of declarative controls.
There are additional utility controls but their purposes are not as generally useful as the ones covered in this post. All of the Chameleon controls will be documented when CS2007 is released later this year.
If you have any questions regarding Chameleon, please send them to me via my contact form or add a comment. I will answer all of the questions in the next (and final) post in this series which will be devoted to questions and answers.