Condition Controls

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 default set of condition controls and also provides the mechanism by which you can implement custom conditions (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, the following script will evaluate to true only if the current Post has a video and is approved.

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

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.
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 the value of a property of an object to a predefined value. For example, the following script will evaluate to true if the current Post's PostDate is less than 6/8/2006.

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

All property/value comparison controls expose the following configuration properties:

• ComparisonProperty - Defines the name of the property on the current object whose value will be compared.
  The full list of properties supported by each condition control is available in the Chameleon Control Documentation area of this site.
• 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 - 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 the following script:

<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) - 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. Property comparison controls provide a way to implement conditions based on the comparison of two properties of an object.  For example, the following script will evaluate to true if the current Post's Views count is equal to its Replies count:

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

All property/value comparison controls expose the following configuration properties:

• ComparisonProperty1- Defines the name of the property on the current object whose value will be compared.
• ComparisonProperty2- Defines the name of the property on the current object whose value will be compared to the value of ComparisonProperty1.
  The full list of properties supported by each conditoin control is available in the Chameleon Control Documentation area of this site.
• Operator (Contains, EndsWith, EqualTo, GreaterThan, GreaterThanOrEqualTo, LessThan, LessThanOrEqualTo, StartsWith, IsSetOrTrue) - 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 />) - Provides a way to define conditions based on the visibility of a specific control on the current page. ControlVisibilityCondition defines the following configuration properties:
  • ControlId - ID of the control on the current page whose visibility will be compared.
  • ControlVisibilityEquals - 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 ControlVisibility Condition to be true.
• UserInRoleCondition (<CSControl:UserInRoleCondition />)-
  Provides a way to define conditions based on a user's role membership. This control exposes the following configuration properties:
  • Role - Name of the role that the user must be in for this condition to evaluate to true.
  • 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 />)- 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 />) - 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 in SiteUrls.config. If the current page is accessed as the URL defined by SiteUrlName, then 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 />) - Adds support for code-based conditions by exposing a single property, CustomResult, which can be set to the result of custom code.  For example, the following script will evaluate to true only if the server time is within the noon hour:

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

These controls can be used by theme developers to implement a wide range of conditional rendering in their themes.  For example, the following script will 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):

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