In this post, I'll outline the changes to the Chameleon theming engine (and themes in general) between Community Server 2007 and Community Server 2008. If you're interested in the changes to themes between an earlier version of Community Server (before 2007) and the 2008 version, I suggest reading my Introduction to Chameleon posts from the release of CS2007.
New Functionality
Community Server 2008 merges the File Gallery and Photo Gallery applications into a single Media Gallery application. New messaging support (activities, profile comments, profile announcements, and private conversations) and support for sub-communities (groups) was also added. For all of the new API objects, there are new Chameleon controls. Also, for all of the new UI locations, Community Server expects new pages to exist in themes.
In terms of themes and Chameleon, this means:
- All controls with the <CSFile:> and <CSGallery:> prefix from CS2007 no longer exist in CS2008 -- they cannot be used anywhere in a CS2008 theme.
- All theme pages in the Files/, Galleries/, and Roller/ folders of a theme are no longer used.
- There are now controls with the prefix <CSMedia:>, <CSMessage:> and <CSHub:> to support accessing media gallery, messaging, and sub-community (group) content (respectively). Documentation for these new controls is coming as soon as our CS2008 documentation sites are publicly available (I'll make an announcement on my blog when that happens).
- Pages linking to or displaying private messages must now use the new <CSMessage:> controls.
- The "PrivateMessage" and "UserPrivateMessages" values for the LinkTo property of the <CSControl:UserData /> control should be changed to "SendConversationMessage" and "UserConversations" (respectively).
- The User/privatemessagelist.aspx theme page is no longer used.
- The following pages were added:
- User/activitylist.aspx
Lists activity messages for a user - User/announcementlist.aspx
Lists announcements made by a user - User/commentlist.aspx
Lists comments made on a user - User/conversation.aspx
Displays a single conversation - User/conversationlist.aspx
Lists all conversations for the accessing user - User/createeditconversation.aspx
Starts and enables replying to a conversation - User/createeditprofilemessage.aspx
Adds a comment on a user or Adds and supports editing an announcement - User/editapikeymodal.aspx
Edits a REST API key - User/editapikeys.aspx
Lists and manages REST API keys - User/favoritelist.aspx
Lists a users favorite posts and sections - User/friendshiplist.aspx
Lists all friends for a current user and provides support for accepting and reviewing friendship requests - User/requestfriend.aspx
Initiates a friendship request - User/userfile.aspx
Displays a single file uploaded into a user's "My Files" area - User/userfilelist.aspx
Lists files uploaded into a user's "My Files" area - User/userfileslideshow.aspx
Displays a slideshow of files in a user's "My Files" area - Utility/insertmedia.aspx
Renders the "Insert Media" window used by the editor to insert file viewers for external or local media - Media/*
All files in the Media/ folder are new and are used to render the Media Gallery application pages - Hubs/*
All files in the Hubs/ folder are new and are used to render aggregate group information (Groups are called Hubs in the API, Chameleon, and themes)
- The old "Default" theme was renamed to "Calypso" -- so there is no longer a "Default" theme. This was done to prevent the need to overwrite the default theme in future versions of Community Server which may cause issues with saved Dynamic Configuration options. This change a few implications for existing themes that referenced files in the "Default" theme:
- The UserWelcome.ascx user control used to render the "Sign In", "Sign Out", "Help" and other links (usually in the upper-right of a Community Server site) must be copied into new themes or the theme should be updated to reference the shared version of this user control located at utility/UserControls/UserWelcome.ascx
- Ratings controls that reference the star images in the default theme in the ImagesBaseUrl property are no longer valid. Such references can be updated to use the shared version of these files located in utility/images.
Removal of Base Page Types
In CS2007, Chameleon required that all ASPX pages inherit from CSThemePage (or one of its sub-classes... CSBlogThemPage, CSFileThemePage, etc). This is no longer the case in CS2008.
To better support integrating content and functionality from Community Server in other ASP.Net-based web applications, Chameleon no longer requires that each ASPX page inherit from CSThemePage. Instead, Chameleon now uses an application-type-specific "page context" object to interpret the querystring, register page headers, etc.
For existing CS2007 themes, no changes are necessarily required. The base theme pages still exist in CS2008 and expose the same functionality (such as the SetTitle() method and CurrentX properties), but, these methods/properties now use the base page context instead of implementing the functionality themselves.
If a theme needs to use a different base page type, all references to the properties and methods of the CSThemPage must be removed (see New General-Purpose Chameleon Controls for more information). The themes that ship with CS2008 should not be dependent on CSThemePage and can be used as a reference on a page-by-page basis.
In CS2007, the base page types also identified the application-type context for the page. This application-type context was used to interpret post IDs/names, section IDs/names, etc (if the application-type context was "weblog" for example, Chameleon would attempt to interpet a post ID on the query string as a blog post). In CS2008, the application-type context is now set by the applicationType attribute on <location /> and <url /> nodes in the SiteUrls.config file.
Changes to Existing Chameleon Controls
With respect to the topic further down the page (Property Templates), there are very few changes to existing Chameleon controls and none of the implemented changes should impact existing themes.
Here is an overview of the changes, by control type:
API-related Single Value Controls
The following properties were added to API-related Single Value Controls:
- LinkTabIndex
Defines the tab-index for the link identified by the LinkTo property. - EnsureVisibleHtml
When set to true (the default is false), the content of the control will only be rendered if the value of the defined Property or ExtendedAttribute contains visible HTML -- that is, text or <img />, <object />, <embed />, <applet />, or <iframe /> tags. This setting is helpful when determining whether to show content entered from an HTML editor. - IgnoreLinkPermissions
When set to true (the default is false), the link identified by the LinkTo property will be rendered regardless of the accessing user's permissions to that link. For example, in forums, the "Reply" link is displayed even for users who do not have access to reply to a post. When the link is clicked, the user is either asked to log in or alerted that they do not have access to reply. - Encoding (None, HTML, JavaScript, URL)
To help remove the need to use inline code, the Encoding property was added. When set (the default is None), the value of the defined Property or ExtendedAttribute will be encoded for the identified output -- HTML, JavaScript or URL. This property is useful when including dynamic content within inline JavaScript scripts or with property templates (defined below) that will be included in URLs.
API-related Condition Controls
API-related Condition Controls, such as XPropertyValueComparison and XPropertyComparison, now support an additional value for the Operator property: ContainsVisibleHtml. Using this operator will cause the condition to evaluate to true only if the "left" value contains visible HTML (visible text or <img />, <object />, <embed />, <applet />, or <iframe /> tags).
List Controls
All list controls in CS2008 now support paging (a few did not in CS2007).
Additionally, all list controls support a new control type called "Query Implementations." Query implementation controls are used to override the default execution of a query. They inherit from QueryImplementationBase and are passed the populated API-object representing the query defined by a list control and are expected to return a list matching that query. The query implementation control can execute the query however it wishes -- it could load data from an XML file, perform advanced sorting, add new rating functionality, etc.
Query implementations are defined within the <QueryOverride /> definition for a list, for example:
<CSControl:UserList runat="server">
<QueryOverrides PagerSize="10" PageIndex="0">
<MyCustomControl:MyQueryImplementation runat="server" />
</QueryOverrides>
</CSControl:UserList>
<CSControl:SiteUrl /> and <CSControl:ModifiedUrl />
The <CSControl:SiteUrl /> control is used to render a link to a specific URL defined in the SiteUrls.config file and the <CSControl:ModifiedUrl /> control is used to render a link to a modified version of the current URL... but what if you want to render the URL and not a link to the URL?
In CS2008, these controls now support the RenderRawUrl property which, when set to true (it defaults to false), will render the URL as text instead of in an <a /> tag. This is useful when the URL needs to be rendered into a JavaScript script or in plain text for copying/pasting from a rendered page.
New General-Purpose Chameleon Controls
There are a few additional Action and Utility controls that will be browseable once the new Chameleon Documentation finds a home in the CS2008 documentation sites, but I want to draw specific attention to a few new controls:
<CSControl:Title />
The <CSControl:Title /> control should be used (in new themes at least) in place of using the SetTitle() method (as was defined on CSThemePage-based ASPX pages) to set the page title. The <CSControl:Title /> control is a Single Value control that, by default, does not render any content to the page but sets the title of the current HTML page. It supports the following properties:
- EnableRendering
If set to true (the default is false), the control will be rendered as well as used to set the page title. Any HTML in or around the rendered control will be removed when setting the page title, but will be rendered in the location of the <CSControl:Title /> control. Also note that the <LeaderTemplate /> and <TrailerTemplate /> contents will not be assigned to the page title (but will be rendered in place when EnableRendering is set to true). - IncludeSiteName
When set to true (the default is false), the page title will be updated to include the site's name. Note that this property does not affect the rendered title (when EnableRendering is set to true), only the page title. - IncludeSectionOrHubName
When set to true (the default is false), the page title will be updated to include the current section or hub's name (if a section or hub exists in the page's context). Note that this property does not affect the rendered title (when EnableRendering is set to true), only the page title. - Text
The text to use as the title (overridden by the ResourceName property and the <ContentTemplate /> template). - ResourceName
The name of the language resource to use as the title (overridden by the <ContentTemplate /> template). - ResourceFile
The file name containing the language resource identified by the ResourceName property.
<CSControl:SetQueryOverridePropertyAction />
If you've seen the Hawaii theme in CS2008, you've probably noticed the "Sort By" and "Show" options at the top of some of the pages. Those filters are implemented using Chameleon (no inline code) and the new <CSControl:SetQueryOverridePropertyAction /> control. This new Action control, when executed, sets a specific value on the <QueryOverrides /> of a list control. It supports the following properties:
- ListControlId
This is the ID of the list control whose <QueryOverrides /> will be modified. - QueryOverrideProperty
This is the name of the property on the list control's <QueryOverrides /> that should be set. - QueryOverrideValue (<QueryOverrideValueTemplate />)
This is the value to set the defined <QueryOverride /> property to -- it is overridden by the content of the rendered <QueryOverrideValueTemplate /> (see the discussion of Property Templates below for more information).
Control-related Controls
Just as there are Chameleon controls that support displaying, formatting, comparing, and performing actions on API objects, CS2008 includes controls to display, format, compare, and act on other controls using the following Chameleon controls:
- <CSControl:ControlData />
This API-related single value control retrieves and formats property values from another control on the page. This control works like other API-related Single Value Controls, but adds the ControlId property which is used to identify the control to report on. - <CSControl:ControlPropertyComparison />
This condition control supports comparing two properties of a give control. - <CSControl:ControlPropertyValueComparison />
This condition control supports comparing a property of a control to a static value. - <CSControl:SetControlPropertyAction />
Similar to the <CSControl:SetQueryOverridePropertyAction /> identified above, this action control supports setting properties on other controls. Use with care!
Property Templates
To help cut down even more on inline code in themes, many controls now expose templated properties to support setting properties on a control using other Chameleon controls. For example,
<CSControl:SiteUrl UrlName="weblogapplication" runat="server">
<Parameter1Template><CSBlog:WeblogData Property="ApplicationKey" runat="server" /></Parameter1Template>
</CSControl:SiteUrl>
would format the URL named "weblogapplication" from the SiteUrls.config file using the current blog's ApplicationKey, loaded dynamically via the <CSBlog:WeblogData /> control.
Many controls now support property templates, including: <CSControl:SiteUrl />, <CSControl:ModifiedUrl />, <CSControl:ResourceControl />, <CSControl:GoToSiteUrl />, <CSControl:GoToModifiedUrl />, <CSControl:SetQueryOverridePropertyAction />. Using property templates helps to implement more dynamic relationships between content and pages without writing C# code.
API Changes
The point of some of the Chameleon changes in CS2008 is to remove the dependency on the API. Chameleon, like the REST API for developers, buffers theme developers from internal code changes in Community Server. In CS2007, some functions required the use of API methods -- methods to set the page title, get current objects, perform formatting, etc. While CS2008 aims to remove some of these necessary code-based interactions with the underlying CS API, existing CS2007 themes that directly accessed the CS API via inline code may need to be updated.
The following API methods (that may have been used in CS2007 themes) no longer exist:
- CommunityServer.Components.Formatter.FormatEnum()
- CommunityServer.Components.Formatter.FormatAgoDate()
- CommunityServer.Components.Formatter.FormatDatePost()
- CommunityServer.Components.Formatter.ExpandCollapseIcon()
- CommunityServer.Components.Formatter.Truncate()
- CommunityServer.Components.Formatter.CheckStringLength()
- CommunityServer.Components.Formatter.GetBodySummary()
- CommunityServer.Components.Formatter.StripAllTags()
- CommunityServer.Components.Formatter.WhiteSpace()
- CommunityServer.Components.Formatter.FormatUsername()
- CommunityServer.Discussions.Components.FormatPrivateMessageRecipients()
Any references to these API methods should be removed from CS2007 themes being migrated to CS2008. In general, I'd suggest staying away from accessing the CS API programmatically in themes if possible.
Any questions regarding these changes? Please ask me in the comments.
In my next article, I'll identify the specific changes that should be made to CS2007 themes to support CS2008.