Introduction to Chameleon: Condition Controls

All Posts

Your browser must support javascript to use the posts pager. Please enable javascript or return to the home page to page through posts.

May 9	Community Server 2008 Hack-a-thon
May 8	What is a Good Online Video Service for Screencasts...
May 5	Community Server 2008 - Groups Overview
Apr 26	Dynamic Navigation Add On for Community Server
Apr 24	Community Server 2008 - Centralized File...
Apr 23	Community Server 2008 - Implementing Custom...
Apr 21	Improved Chameleon Documentation for Community...

Search getben.com

Browse by Tags

The Book

The book all about implementing themes in Community Server.

Get it at Amazon or Barnes and Noble

Syndication

Introduction to Chameleon: Condition Controls

This is a post in my blog series Introduction to Chameleon...

Condition controls evaluate theme-developer-defined criteria for use by other controls.

Condition controls are commonly used by other Chameleon controls (such as single value controls, list controls, and form controls) to define conditions under which they should render. Rendering conditions are defined using the "DisplayCondtions" inner-property.

Chameleon includes a set of condition controls which are available by default and also provides the mechanism by which custom conditions can be implemented (all inherit from ConditionBase). Existing condition controls include:

Conditions (<CSControl:Conditions />)

The Conditions control provides support for combining the results of one or more other condition controls. For example,

<CSControl:Conditions Operator="And" runat="server">
<CSControl:PostPropertyValueComparison runat="server" ComparisonProperty="HasVideo" Operator="IsSetOrTrue" />
<CSControl:PostPropertyValueComparison runat="server" ComparisonProperty="IsApproved" Operator="IsSetOrTrue" />
</CSControl:Conditions>

would evaluate to true only if the current Post has a video and is approved.

The Conditions control exposes only one property, "Operator", which is used to define the method by which the contained condition controls will be evaluated. Supported values are: Or, And, ExclusiveOr, and Not.

"DisplayConditions", the inner-property defined on Chameleon controls to support conditional rendering, is a Conditions control.

Note that Conditions controls can contain other Conditions controls. Nesting Conditions controls is useful when implementing complex rendering requirements.
Property and Value Comparison Condition

For each data type within the Community Server API, a property/value comparison condition control is defined. The property/value comparison controls provide a way to implement conditions based on the comparison of a value of a property of an object to a predefined value. For example,

<CSControl:PostPropertyValueComparison runat="server" ComparisonProperty="PostDate" ComparisonValue="6/8/2006" Operator="LessThan" />

would evaluate to true if the current Post's PostDate is less than 6/8/2006. All property/value comparison controls expose the following configuration properties:

ComparisonProperty

ComparisonProperty defines the name of the property on the current object whose value will be compared.
ComparisonValue

ComparisonValue defines the static value to compare to the value of the ComparisonProperty. If the ComparisonProperty is a DateTime value, ComparisonValue can be set to "today" or "now" to specify the current date or date and time.
ComparisonValueAdjustment

ComparisonValueAdjustment defines a number to be used to adjust the ComparisonValue. This is most useful when specifying "today" or "now" for the ComparisonValue in which case the specified number of ComparisonValueAdjustmentUnits are added to "today" or "now" before processing the condition.

The value of ComparisonValueAdjustment is only used when the ComparisonProperty is a DateTime, int, or double value.
ComparisonValueAdjustmentUnit (Minute, Hour, Day, Month, Year, Default)

When a ComparisonValueAdjustment is specified, ComparisonValueAdjustmentUnit identifies the unit of the adjustment value. For example, to check to see if a specific post was made within the last 24 hours, you could use:

<CSControl:PostPropertyValueComparison runat="server" ComparisonProperty="PostDate" Operator="GreaterThan" ComparisonValue="now" ComparisonValueAdjustment="-24" ComparisonValueAdjustmentUnit="Hour" />

When ComparisonProperty is an int or double and a ComparisonValueAdjustment is specified, the ComparisonValueAdjustmentUnit is irrelevant. The default unit for DateTime adjustments is 'Day'.
Operator (Contains, EndsWith, EqualTo, GreaterThan, GreaterThanOrEqualTo, LessThan, LessThanOrEqualTo, StartsWith, IsSetOrTrue)

Operator defines the method by which ComparisonProperty's value is compared to the ComparisonValue.

When Operator is set to "IsSetOrTrue", the ComparisonValue is ignored.

Property Comparison Condition

As with property/value controls, a property comparison control is defined for each data type within the Community Server API as well. Property comparison controls provide a way to implement conditions based on the comparison of two properties of an object. For example,

<CSControl:PostPropertyComparison runat="server" ComparisonProperty1="Views" ComparisonProperty2="Replies" Operator="EqualTo" />

would evaluate to true if the current Post's Views count is equal to its Replies count. All property/value comparison controls expose the following configuration properties:
1. ComparisonProperty1
  
  ComparisonProperty1 defines the name of the property on the current object whose value will be compared.
2. ComparisonProperty2
  
  ComparisonProperty2 defines the name of the property on the current object whose value will be compared to the value of ComparisonProperty1.
3. Operator (Contains, EndsWith, EqualTo, GreaterThan, GreaterThanOrEqualTo, LessThan, LessThanOrEqualTo, StartsWith, IsSetOrTrue)
  
  Operator defines the method by which ComparisonProperty1's value is compared to ComparisonProperty2's value.
  
  When Operator is set to "IsSetOrTrue", the value of ComparsionProperty2 is ignored.
ControlVisibilityCondition (<CSControl:ControlVisibilityCondition />)

ControlVisibilityCondition provides a way to define conditions based on the visibility of a specific control on the current page. ControlVisibilityCondition defines the following configuration properties:
1. ControlId
  
  ControlId is the ID of the control on the current page whose visibility will be compared.
2. ControlVisibilityEquals
ControlVisibilityEquals is a boolean defining the visibility value that will cause this condition to be true.

For example, if ControlVisibilityEquals is set to "true", the control whose id is defined by ControlId must be visibile for the ControlVisibilityCondition to be true.
UserInRoleCondition (<CSControl:UserInRoleCondition />)

UserInRoleCondition provides a way to define conditions based on a user's role membership. This control exposes the following configuration properties:
1. Role
  
  Role is the name of the role that the user must be in for this condition to evaluate to true.
2. UseAccessingUser
  
  If true, the user accessing the page will be used when checking role membership. If false, the current user according to the context of the UserInRoleCondition control will be used when checking membership in the specified role.
SectionPermissionCondition (<CSControl:SectionPermissionCondition />)

SectionPermissionCondition provides a way to define conditions based on a user's permissions to the current section. This control exposes only one configuration property, "Permission", which is the name of the permission required by the user accessing the page. If the user accessing the page has the specified permission for the current section (or section and post), the SectionPermissionCondition control evaluates to true, otherwise false.
CurrentSiteUrlCondition (<CSControl:CurrentSiteUrlCondition />)

CurrentSiteUrlCondition provides a way to define conditions based on the current URL being accessed from the SiteUrls.config file. This control exposes only one configuration property, "SiteUrlName", which is the name of a URL is SiteUrls.config. If the current page is accessed as the URL defined by SiteUrlName, CurrentSiteUrlCondition evaluates to true.

This control is useful in situations where multiple URLs in SiteUrls.config are rendered using one physical ASPX page but minor variations should be rendered depending on the specific URL being accessed.
CustomCondition (<CSControl:CustomCondition />)

CustomCondition adds support for code-based conditions by exposing a single property, CustomResult, which can be set to the result of custom code. For example:

<CSControl:CustomCondition runat="server" CustomResult='<%# DateTime.Now.Hour == 12 %>' />

will evaluate to true only if the server time is within the noon hour.

These controls can be used by theme developers to implement a wide range of conditional rendering in their themes. For example,

<CSBlog:WeblogPostData Text="{0} comment(s)" Property="Replies" LinkTo="PostComments" runat="server">
   <DisplayConditions>
      <CSBlog:WeblogPostPropertyValueComparison runat="server" ComparisonProperty="Replies" ComparisonValue="0" Operator="GreaterThan" />
   </DisplayConditions>
</CSBlog:WeblogPostData>
<CSBlog:WeblogPostData Text="no comments" LinkTo="PostComments" runat="server">
   <DisplayConditions>
      <CSBlog:WeblogPostPropertyValueComparison runat="server" ComparisonProperty="Replies" ComparisonValue="0" Operator="LessThanOrEqualTo" />
   </DisplayConditions>
</CSBlog:WeblogPostData>

will show either the number of comments on the current blog post (if greater than 0) or the text "no comments" (if no comments have yet been made).

If you have any questions regarding Chameleon, please send them to me via my contact form or add a comment. I will answer all the questions in the final post in this series.

In my next post in this series, I will discuss Action controls.

Published January 15, 2007

Filed under: Community Server, Software Development, Theming, Chameleon, CS2008, CS2007

Comments

techSage wrote re: Introduction to Chameleon: Condition Controls

on 03-08-2007 1:20 PM

Ben,

I tried adding a DisplayConditions control to the /Themes/default/Forums/grouplist.aspx like this:

<CSForum:ForumList runat="server">

<CSControl:SectionPermissionCondition Permission="Read" runat="server"/>

</DisplayConditions>

but the ForumList control *never* renders, even for an Administrator. Is my syntax wrong for this? Thanks.

Ben Tiedt wrote re: Introduction to Chameleon: Condition Controls

on 03-08-2007 2:31 PM

techSage -- The SectionPermissionCondition will always evaluate to false if there is no Section in the current context. Only the ItemTemplate and AlternatingItemTemplate of the ForumList control will have a Section in the current context (unless a parent of the ForumList control is binding Sections).

You can use the SectionPermissionCondition within the ItemTemplate, such as:

<CSForum:ForumList runat="server">

<CSControl:PlaceHolder runat="server">

... section content here...

</ContentTemplate>

</CSControl:PlaceHolder>

</ItemTemplate>

</CSForum:ForumList>

techSage wrote re: Introduction to Chameleon: Condition Controls

on 03-09-2007 11:03 AM

Ben,

Thanks for your reply. First, I think what you've done with the skinning engine in CS2007 is great.

I understand your explanation and I was able to use your suggestion to hide the last post for users that do not have read permissions on that section. What I would like to do is hide the listing of some forums for non-registered users, but still show the group names to intrigue the user into joining.

The nice thing would be if forum groups have their own "View" permission that does not rely on the permissions of child forums, but I think that is not likely to happen since it is possibly an uncommon request.

So, to accomplish what I want, would I need to wrap the HeaderTemplate, ItemTemplate and FooterTemplate (basically everything inside of the ForumList control that specifies the rendering of the listing of forums in a particular group) in a control that sees the section of the current item (forum) being rendered?

Thanks again for taking the time to consider this. I realize you must be very busy with CS.

Ben Tiedt wrote re: Introduction to Chameleon: Condition Controls

on 03-09-2007 11:48 AM

techSage -- CS is designed to allow users to see forums but not read them (View without Read permission)... so you're going a step up from that...

You can definitely use the existing SectionPermissionCondition to check for view access within the item -- but your header/footer would always display. The header/footer/leader/trailer templates of lists are not bound, so you don't have a Section in the current context to check.

One option would be to create a custom Conditions control (inherit from CommunityServer.Controls.ConditionBase) and use CommunityServer.Discussions.Controls.ForumControlUtility.Instance().GetCurrentGroup(Control) to retrieve the current group and perform the checks for view access at the group level. Then, this new control could be used as a DisplayCondition for your ForumList control to hide the entire list if *no* sections have Read permissions.

Jared wrote re: Introduction to Chameleon: Condition Controls

on 04-02-2007 10:23 AM

Ben,

You say in the post that "For each data type within the Community Server API, a property/value comparison condition control is defined."

Is this API documented anywhere publicly? Will it be part of the new release? I'm trying to write conditionals and have no way of knowing what all the property/values that are exposed are.

Thanks for the great posts and any help. We are really looking forward here to using Community Server 2007.

- Jared

Ben Tiedt wrote re: Introduction to Chameleon: Condition Controls

on 04-02-2007 11:22 PM

Jared -- The Control/API documentation should be available around the time that CS2007 is released. In previous versions of CS, there was little or no documentation.