Community Server 2008: Changes to Chameleon : Community Server 2008 Support

Community Server 2008: Changes to Chameleon

Telligent has made a number of changes to the Chameleon theming engine (and themes in general) between from Community Server 2007. The following summary describes those changes.

New Functionality

Community Server 2008 merges the File Gallery and Photo Gallery applications into a single Media Gallery application. We also added new messaging support (activities, profile comments, profile announcements, and private conversations) and support for sub-communities (groups). For all of the new API objects, there are new Chameleon controls, and the themes have new pages.

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.
Community Server no longer uses any of the theme pages in the themes’ Files/, Galleries/, and Roller/ folders.
Controls with the prefixes <CSMedia:>, <CSMessage:> and <CSHub:> support access to media gallery, messaging, and sub-community (group) content respectively.
Pages linking to or displaying private messages must now use the new <CSMessage:> controls.
You should change the PrivateMessage and UserPrivateMessages values for the LinkTo property of the <CSControl:UserData /> control to SendConversationMessage and UserConversations respectively.
The User/privatemessagelist.aspx theme page is no longer used.
The following pages were added:

User/activitylist.aspx - Lists a user’s activity messages.
User/announcementlist.aspx - Lists a user’s announcements.
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 replies to a conversation.
User/createeditprofilemessage.aspx - Adds a comment on a user or adds and supports announcement editing.
User/editapikeymodal.aspx - Edits a REST API key.
User/editapikeys.aspx - Lists and manages REST API keys.
User/favoritelist.aspx - Lists a user’s 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 all 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 Community Server 2007 Default theme is renamed Calypso. This prevents having to overwrite the default theme in future versions of Community Server, which can cause issues with saved Dynamic Configuration options. However, this has a few implications for existing themes that reference files in the Default theme:

You must copy 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) into new themes or update the theme 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. You can update such references to use the shared version of these files located in utility/images.

Removal of Base Page Types

In Community Server 2007 Chameleon required that all ASPX pages inherit from CSThemePage (or one of its sub-classes, such as CSBlogThemPage, CSFileThemePage, etc.). This is no longer the case in Community Server 2008.

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.

You do not necessarily have to change anything for existing Community Server 2007 themes. The base theme pages still exist in Community Server 2008 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, you must remove all references to the properties and methods of the CSThemPage (see New General Purpose Chameleon Controls for more information). The themes that ship with Community Server 2008 should not be dependent upon CSThemePage and they can be used as a reference on a page-by-page basis.

In Community Server 2007, the base page types also identified the application-type context for the page. This application-type context interpreted post IDs/names, section IDs/names, etc. If the application-type context was weblog, for example, Chameleon attempted to interpret a post ID on the query string as a blog post. In Community Server 2008, the applicationType attribute on <location /> and <url /> nodes in the SiteUrls.config file sets the application-type context.

Changes to Existing Chameleon Controls

With respect to Property Templates, Community Server 2008 change very few 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

Community Server 2008 added the following properties 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 setting is false), the content of the control is rendered only 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 setting is false), the link identified by the LinkTo property is rendered regardless of the accessing user's permissions to that link. For example, Community Server displays the Reply link even for users who do not have access to reply to a post. When the user clicks on the link, the user is asked either to log in or is alerted that they do not have access to reply.
Encoding (None, HTML, JavaScript, URL) – Community Server added the Encoding property so inline code is no longer necessary. When you set the property value (the default is None), the value of the defined Property or ExtendedAttribute is encoded for the identified output: HTML, JavaScript or URL. This property is useful when you are 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. This control causes 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 Community Server 2008 support paging.

Additionally, all list controls support a new control type called Query Implementations. Query Implementation controls override the default execution of a query. They inherit from QueryImplementationBase. The populated API-object representing the query defined by a list control is passed to the Query Implementations control and they return a list matching that query. The query implementation control can execute the query however it wants: it can 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 renders a link to a specific URL defined in the SiteUrls.config file. The <CSControl:ModifiedUrl /> control renders a link to a modified version of the current URL.

In Community Server 2008, these controls support the RenderRawUrl property which, when set to true (it defaults to false), renders 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 are browseable in the Chameleon control documentation.

<CSControl:Title />

You should use the <CSControl:Title /> control in new themes in place of 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 instead sets the title of the current HTML page. It supports the following properties:

EnableRendering
If set to true (the default is false), the control is rendered and sets the page title. Any HTML in or around the rendered control is removed when you set the page title, but it is rendered in the location of the <CSControl:Title /> control. Also note that the <LeaderTemplate /> and <TrailerTemplate /> contents are not assigned to the page title (but are rendered in place when EnableRendering is set to true).
IncludeSiteName
When set to true (the default is false), the page title is updated to include the site name. This property affects only the page title, not the rendered title, when you set EnableRendering to true.
IncludeSectionOrHubName
When set to true (the default is false), the page title is updated to include the current section or hub name (if a section or hub exists in the page's context). This property affects only the page title, not the rendered title, when you set EnableRendering to true.
Text
This text is used as the title (overridden by the ResourceName property and the <ContentTemplate /> template).
ResourceName
This is the name of the language resource to use as the title (overridden by the <ContentTemplate /> template).
ResourceFile
This is the file name containing the language resource identified by the ResourceName property.

<CSControl:SetQueryOverridePropertyAction />

The Sort By and Show options at the top of some of the pages are implemented using Chameleon (no inline code) and the <CSControl:SetQueryOverridePropertyAction /> Action control. This control 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.
QueryOverrideValue (<QueryOverrideValueTemplate />)
This is the value to set the <QueryOverride /> property. The content of the rendered <QueryOverrideValueTemplate /> overrides this control.

Control-related Controls

Just as there are Chameleon controls that support displaying, formatting, comparing, and performing actions on API objects, Community Server 2008 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 identifies the control to report on.
<CSControl:ControlPropertyComparison />
This condition control compares two properties of a given control.
<CSControl:ControlPropertyValueComparison />
This condition control compares a control property to a static value.
<CSControl:SetControlPropertyAction />
Similar to the <CSControl:SetQueryOverridePropertyAction />, this action control allows you to set properties on other controls.

Property Templates

To help cut down even more on inline code in themes, many controls expose templated properties so you can set properties on a control using other Chameleon controls. For example, the following control

<CSControl:SiteUrl UrlName="weblogapplication" runat="server">
<Parameter1Template><CSBlog:WeblogData Property="ApplicationKey" runat="server" /></Parameter1Template>
</CSControl:SiteUrl>

formats 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 implement more dynamic relationships between content and pages without writing C# code.

API Changes

The purpose of some of the Chameleon changes in Community Server 2008 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 Community Server 2007, some functions required the use of API methods, such as setting the page title, getting current objects, formatting, etc. While Community Server 2008 aims to remove some of these necessary code-based interactions with the underlying Community Server API, you may have to update existing Community Server 2007 themes that directly access the Community Server API via inline code.

The following API methods you may have used in Community Server 2007 themes do not exist in Community Server 2008:

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()

You should remove any references to these API methods from Community Server 2007 themes being migrated to Community Server 2008. Telligent recommends you avoid accessing the Community Server API programmatically in themes whenever possible.