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

As I mentioned in the Differences from CS2.1 and Earlier post, Chameleon uses a set of general purpose controls based on the Community Server API.  These controls fall into a few categories:

  1. Single value controls
  2. List controls
  3. Form controls
  4. Condition controls
  5. Action controls
  6. Utility controls

I'll cover single value controls in today's post.

 

Single value controls display a single value (language resource, pop-up menu, etc) or set of values for a single API object (post, user, section, group, etc), for example, the UserData control, which can be as simple as:

<CSControl:UserData runat="server" Property="DisplayName" />

which would render my name, "Ben Tiedt" (with no additional markup), or as customized as:

<CSControl:UserData ContainerId="WrapperID" Tag="H2" CssClass="WrapperClass" Property="DisplayName" LinkTo="Profile" unrecognized="true">
   <DisplayConditions Operator="And">
      <CSControl:QueryStringPropertyValueComparison runat="server" QueryStringProperty="ShowName" ComparisonValue="true" Operator="EqualTo" />
      <CSControl:UserInRoleCondition runat="server" Role="Moderators" />
   </DisplayConditions>
   <LeaderTemplate>
      I'm a moderator and my <u>name</u> is
   </LeaderTemplate>
   <TrailerTemplate>
      .  So there!
   </TrailerTemplate>
</CSControl:UserData>

which would render the source:

<h2 class="WrapperClass" id="WrapperID" unrecognized="true">I'm a moderator and my <u>name</u> is <a href="http://getben.com/user/Profile.aspx?UserID=2108">Ben Tiedt</a>.  So there!</h2>

where the H2 tag represents the content wrapper and leader and trailer templates further wrap the content within the content wrapper (H2) tag.  Note that this would only render if the querystring of the page included "ShowName=true" and I am a member of the "Moderators" role due to the defined DisplayConditions.  I'll talk about conditions in a later post.

All single value controls support the following properties (and inherit from WrappedContentBase):

  1. ControlIdsToHideWhenNotVisible

    ControlIdsToHideWhenNotVisible is useful when using non-Chameleon controls.  If the DisplayConditions of this control cause the control to not be rendered, controls identified by ControlIdsToHideWhenNotVisible will also be set to not render (Visible=false).  This property is a comma-separated list of control IDs.
  2. ContainerId

    ContainerId simply identifies the client-rendered ID content wrapper.  The ID is not guaranteed to be unique by ASP.net (as the normal ID/ClientID is) and should be used solely for cascading style sheets.

    Note that the content wrapper only renders if ContainerId, CssClass, Tag, and/or Attributes are set.
  3. CssClass

    CssClass identifies the CSS class name (or names) to apply to the content wrapper.

    Note that the content wrapper only renders if ContainerId, CssClass, Tag, and/or Attributes are set.
  4. Tag

    Tag is the tag name of the content wrapper.  Tag is of type WrappedControlTag, which identifies common tag names.

    Note that the content wrapper only renders if ContainerId, CssClass, Tag, and/or Attributes are set.
  5. DisplayConditions

    DisplayConditions is an inner-property of type Conditions that identifies the conditions under which this control should be rendered.  If defined, the control will only render if DisplayConditions resolves to true.

    I'll cover the Condition controls in a seperate post.
  6. LeaderTemplate

    LeaderTemplate is an inner-property containing markup and controls to render before the content of the control and within the content wrapper.  The LeaderTemplate is databound and supports rendering properties from the DataSource.

    For example, the LeaderTemplate could be defined as:

    <LeaderTemplate>
       <%# Eval("DisplayName") %>
    </LeaderTemplate>

    in the UserData example above and would evaluate to the user's display name.
  7. TrailerTemplate

    TrailerTemplate is an inner-property containing markup and controls to render after the content of the control and within the content wrapper.  The TrailerTemplate is databound and supports rendering properties from the DataSource.
  8. DataSource

    Self-explanatory to ASP.net users, the DataSource is implicitly defined and bound if not otherwise programmatically overridden.
  9. Attributes

    Chameleon controls implement IAttributeAccessor and render any unrecognized properties as attributes on the content wrapper.  In the example above, the "unrecognized" property was passed through to the content wrapper tag (H2) because of attributes support--the "unrecognized" property is not a property defined on Chameleon controls.

    Note that the content wrapper only renders if ContainerId, CssClass, Tag, and/or Attributes are set.

In the UserData control example above, I also used the properties Property and LinkTo.  These properties are common to API-related controls (which inherit from ObjectDataBase).  API-related controls are named based on the underlying type (User, Post, etc), so there are controls such as:

  • UserData (<CSControl:UserData />)
  • PostData (<CSControl:PostData />)
  • SectionData (<CSControl:SectionData />)
  • GroupData (<CSControl:GroupData />)
  • etc...

and also, application-specific controls such as:

  • WeblogData (<CSBlog:WeblogData />)
  • WeblogPostData (<CSBlog:WeblogPostData />)
  • ForumData (<CSForum:ForumData />)
  • ForumPostData (<CSForum:ForumPostData />)
  • etc...

When Community Server 2007 is released, we will have documentation on each of these controls, but, they are directly related to the Community Server API -- if you are at all aware of the API, you should already know what the control names and general options are.

Each API-related control automatically retrieves the API object it represents as its DataSource based on the control's context--the UserData control automatically loads the User for the control's context.  If the API object is not available in the control's context, the control will not render.

I'll talk more about implicit databinding in the List control post and I suspect also in the Q&A post.

API-related controls add support for:

  1. Property

    Property is the name of the instance property of the DataSource to render.  By default the value of the property is processed according to its data type and dates are automatically converted to the user's local time.  If Property is specified but the DataSource does not have the specified Property, an exception is raised.  If the specified property is null or not set, the control will not render.
  2. ExtendedAttribute

    If Property is not defined, ExtendedAttribute will be used to determine the value to render in the content of the control.  If the DataSource extends the ExtendedAttributes class, the extended attribute value will be retrieved and displayed as the content of the control.
  3. FormatString

    The FormatString will be used to format the value identified by the Property attribute.  Any .net format string appropriate to the type of the Property are supported.
  4. ResourceName, ResourceFile

    ResourceName/ResourceFile identify a language resource to render as the content of the control.  If specified with a Property or ExtendedAttribute, the formatted value of the Property or ExtendedAttribute is passed as a formatting parameter to the resource identified by ResourceName/ResourceFile.
  5. Text

    Text identifies text to render as the content of the ObjectDataBase control.  If specified with a Property or ExtendedAttribute, the formatted value of the Property or ExtendedAttribute is passed as a formatting parameter to the text identified by Text. 

    Note that if both Text and ResourceName are specified, the Text property is ignored.
  6. TruncateAt

    When specified, the final content of the control is truncated at the given length.  If the content contains HTML, the HTML mark-up is stripped before truncation.
  7. TruncationEllipsisText/TruncationEllipsisResourceName/TruncationEllipsisResourceFile

    When the content is truncated, the value of TruncationEllipsisText or the language resource identified by TruncationEllipsisResourceName/TruncationEllipsisResourceFile is appended to the truncated content (if a resource name is specified, it overrides the text property) .  TruncationEllipsisText defaults to "...".

    With Community Server 2007 SP3, support for TruncationEllipsisTemplate was added.  TruncationEllipsisTemplate overrides TruncationEllipsisText and TruncationEllipsisResourceName/TruncationEllipsisResourceFile to render custom markup and controls when the content of the control is truncated.  The TruncationEllipsisTemplate is databound.
  8. IncludeTimeInDate

    If Property is a DateTime, setting IncludeTimeInDate to true will render the time along with the date.  This property defaults to false.
  9. ContentTemplate

    ContentTemplate is an inner-property containing markup and controls to render as the content of the control.  Setting ContentTemplate overrides Property, FormatString, ResourceName, ResourceFile, Text, TruncateAt, and IncludeTimeInDate property values.  The ContentTemplate is databound and supports rendering properties from the DataSource.

    ContentTemplate is useful in cases where you want to perform some programmatic function on a property of a specific API object, for example:

    <CSControl:UserData runat="server">
       <ContentTemplate>
          <%# Eval("DisplayName").ToString().ToLower().Substring(1,1) %>
       </ContentTemplate>
    </CSControl:UserData>

    would render the second character of the user's DisplayName, in lowercase.

 

Additionally, API-related controls expose all related links to the object (post, section, user, etc) via the following properties:

  1. LinkTo

    LinkTo can be set to the name of the link to link the content of the control to.  Each API-related control exposes an enumeration of related links that can be selected (Intellisense is nice for LinkTo properties).

    Note that LinkTo links the content of the control only, not the content wrapper or leader/trailer templates.  It will link content defined by ContentTemplate as well as property-driven content.
  2. LinkQueryStringModification

    When defined, the value is interpreted as a query string whose name/values will be overwritten or appended to the URL of the link.  For example, if the LinkTo URL would normally evaluate to

    this.aspx?value1=1&value2=2

    and LinkQueryStringModification was set to

    value1=5&value3=3

    the resulting link URL would be

    this.aspx?value1=5&value2=2&value3=3
  3. LinkTargetLocationModification

    When defined, the value is interpreted as a target location (#targetLocation) which will overwrite the existing target location or be appended to the URL of the link.  For example, if the LinkTo URL would normally evaluate to

    this.aspx?value1=1&value2=2#target

    and LinkTargetLocationModification was set to

    newtarget

    the resulting link would be

    this.aspx?value1=1&value2=2#newtarget
  4. LinkCssClass

    The CSS class to apply to the link (class of the <a> tag).
  5. LinkRel

    The relationship of the linked document to the current document.
  6. LinkTarget

    The target window of the link (target of the <a> tag).
  7. LinkTitleText/LinkTitleResourceName/LinkTitleResourceFile

    The title to apply to the link.  If LinkTitleResourceName is defined, it overrides LinkTitleText.

    When the content that is being linked is truncated (via the TruncateAt property), the default link title is the full text of the content.

Understanding these properties provides knowledge of all single-value/single-object controls--

they all work the same way (and are mostly implemented by their base classes). 

 

I thought it would be useful to include a complete example of a Chameleon page at this point.  I have attached the default main blog page (postlist.aspx, see the post footer to access the file).  I suggest reviewing this simple Chameleon page and seeing how the single value controls are used--single value controls should be easy to identify as they usually named somethingDATA.

 

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 Chameleon list controls.