[翻译]Chameleon介绍(2) : 单值控件
这篇文章属于我的文章系列Chameleon介绍...
在我的文章与CS2.1的区别里提到过，Chameleon使用了基于Community Server API的一系列通用控件。这些控件分为以下几类：
今天的文章里将会介绍单值控件。
单值控件代表了单个的值（语言资源，弹出菜单，等等）或者单个API对象（帖子，用户，节（译注：CS里把论坛分版，博客，相册，下载文件夹等概念统一成节(Section)，作为一个容器，节用于容纳里边的论坛帖子，文章，照片，文件等具体内容。这有点类似于文章系统里的分类的概念），分组，等等等）的一系列值。例如，UserData控件，可以这样简单：
这将会输出我的名字，“Ben Tiedt”（不会添加任何标签）；或者也可以这么自定义：
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>
这将会输出下面的HTML源代码：
<a href="http://getben.com/user/Profile.aspx?UserID=2108">Ben Tiedt</a>. So there!</h2>
这里的H2是内容包装标签，进一步，首部和尾部模板在内容包装标签（H2）内部对内容进行包装。注意只有在页面查询参数包含“ShowName=true”，并且我是“Moderators”角色的成员时才会输出。我会在稍后的另一篇文章里谈谈条件控件。
所有的单值控件都支持以下属性（从WrappedContentBase中继承得到）：
- ControlIdsToHideWhenNotVisible
当使用非Chameleon控件时ControlIdsToHideWhenNotVisible很有用。如果当前控件的DisplayConditions导致此控件不会输出，ControlIdsToHideWhenNotVisible属性所指向的控件也不会输出（Visible=false）。这个属性的值是以逗号间隔的控件ID的列表。
- ContainerId
ContainerId只是简单地指定输出的内容包装标签的客户ID。ASP.net不（像对待常规的ID/ClientId那样）担保这个ID在整个输出页面的唯一性，所以你只应该把它用于层叠样式表。
注意只有当ContainerId,CssClass,Tag,和/或Attributes被设置时内容包装标签才会输出。
- CssClass
CssClass用于指定应用到内容包装标签的CSS类的名称。
注意只有当ContainerId,CssClass,Tag,和/或Attributes被设置时内容包装标签才会输出。
- Tag
Tag是内容包装标签的标签名。Tag的类型是WrappedContentTag，后者代表了常用的标签名。
注意只有当ContainerId,CssClass,Tag,和/或Attributes被设置时内容包装标签才会输出。
- DisplayConditions
DisplayConditions是内置属性（译注：指不是作为XML元素的属性，而是作为一个子元素出现），标识了控件在哪些情况下才应该输出，它的类型是Conditions。如果定义了这个属性，只有当DisplayConditons被解析为真时控件才会输出。
我会在一篇文章里单独介绍条件控件。
- LeaderTemplate
LeaderTemplate是一个内置属性，它能够包含标签和控件。这些标签和控件会在内容包装标签内部，当前控件内容之前输出。LeaderTemplate是数据绑定的，支持输出DataSource的属性。
例如，LeaderTemplate可以在上面的UserData控件的示例中这样使用：
<LeaderTemplate>
<%# Eval("DisplayName") %>
</LeaderTemplate>
这将会计算出用户的呢称（并输出）。 - TrailerTemplate
- DataSource
对ASP.net用户来说它的作用不言而喻。如果没有手工编程改写的话，DataSource将会隐式地定义和绑定。
- Attributes
Chameleon控件实现了IAttributeAccessor接口，把任何不认识的属性作为内容包装标签的属性进行输出。在上面的例子中， “unrecognized”作为属性被传递给内容包装标签（H2），正是因为这样的属性支持——“unrecognized”并不是Chameleon 控件定义的属性。
注意只有当ContainerId,CssClass,Tag,和/或Attributes被设置时内容包装标签才会输出。
在上面的UserData控件示例中，我也使用了属性“Property”和“LinkTo”。这些属性对与API相关的控件（继承自 ObjectDataBase）是很常用的。API相关的控件以它们基于的底层类型（如User，Post，等等）而命名，因此有这些控件：
- UserData（<CSControl:UserData />）
- PostData（<CSControl:PostData />）
- SectionData（<CSControl:SectionData />）
- GroupData（<CSControl:GroupData />）
- 等等...
以及，与特定应用相关的控件诸如：
- WeblogData（<CSBlog:WeblogData />）
- WeblogPostData（<CSBlog:WeblogPostData />）
- ForumData（<CSForum:ForumData />）
- ForumPostData（<CSForum:FroumPostData />）
- 等等...
当Community Server 2007发布后，我们会有每个控件的文档，但是，因为他们直接对应到Community Server的API——如果您对API有一定的了解的话，你应该已经知道了这些控件的名称和大概的选项是什么。
每个API相关的控件都会根据自己所处的上下文，自动获取它代表的API对象，用作DataSource——UserData控件根据自己的上下文自动加载相应的用户对象。如果API对象在上下文中无法获取，控件将不会产生输出。
我会在稍后的列表控件文章里对隐式数据绑定进行更多的介绍，我猜在问与答里应该也会。
API相关控件添加了对下列属性的支持：
- Property
Property是想要输出的DataSource实例的属性名。对于这个属性，不同的数据类型有不同的默认值，并且日期会自动转换到用户的当地时间。如果设置了Property的值，但DataSource并不包含指定的属性，将会引发一个异常。如果指定的属性为null或未设置，控件将不会输出。
- ExtendedAttribute
如果Property未定义，控件将会通过ExtendedAttribute来决定要输出的内容。如果DataSource继承了ExtendedAttributes类，控件将会获取扩展的属性值作为内容进行显示。
- FormatString
FormatString用于对Property属性指定的值进行格式化。它支持任何适合Property类型的.net格式字符串。
- ResourceName，ResourceFile
ResourceName/ResourceFile指定一个语言资源作为控件的内容进行输出。如果同时指定了Property或 ExtendedAttribute，格式化后的Property或ExtendedAttribute值会作为格式化参数传递给由 ResourceName/ResourceFile指定的资源。
- Text
Text指定了作为ObjectDataBase控件的内容进行输出的文本。如果同时指定了Property或ExtendedAttribute，格式化后的Property或ExtendedAttribute的值会作为格式化参数传递给Text指定的文本。
注意如果同时指定了Text和ResourceName，Text属性会被忽略。
- TruncateAt
如果指定了TruncateAt，控件的最终内容将会在给定的长度进行截断。如果内容包含HTML，在截断之前会移除HTML标签。
- TruncationEllipsisText/TruncationEllipsisResourceName/TruncationEllipsisResourceFile
当内容被截断时，TruncationEllipsisText的值，或 TruncationEllipsisResourceName/TruncationEllipsisResourceFile指定的语言资源会追加到截断后的内容上（如果同时提供了两者，TruncationEllipsisResourceName会覆盖Text属性）。 TruncationEllipsisText的默认值是“...”。
- IncludeTimeInDate
如果Property的值是DateTime，设置IncludeTimeInDate为true会输出日期时也输出时间。此属性的默认值是false。
- ContentTemplate
ContentTemplate是一个内置的属性，可以包含标签和控件。这些标签和控件会作为当前控件的内容而输出。设置ContentTemplate 会覆盖Property,FormatString,ResourceName,ResourceFile,Text,TruncateAt，以及 IncludeTimeInDate属性。ContentTemplate支持数据绑定，可以输出DataSource的属性值。
如果你想要对某个属性或API相关对象执行一些编程功能时，ContentTemplate会很有用。例如：
<CSControl:UserData runat="server">
<ContentTemplate>
<%# Eval("DisplayName").ToString().ToLower().Substring(1,1) %>
</ContentTemplate>
</CSControl:UserData>
将会以小写形式输出用户的呢称的第二个字符。
另外，API相关控件通过以下属性暴露了底层对象（帖子，节，用户等等）的所有相关链接：
- LinkTo
LinkTo可以设置为想要把控件内容链接到的位置的名称。每个API相关控件都暴露了一个枚举，里面定义了可选的相关链接（对于LinkTo属性来说智能补全功能很不错）。
注意LinkTo只链接控件内容，而不是控件的包装标签，或首部/尾部模板。它会链接ContentTemplate定义的内容，如同链接Property定义的内容一样。
- LinkQueryStringModification
如果定义了这个属性，它的值会被解释为查询字符串，相应的名称/值会用来改写或添加到链接的URL上。例如，如果LinkTo的URL在正常情况下是
this.aspx?value1=1&value2=2
并且LinkQueryStringModification被设置成
value1=5&value3=3
结果链接URL将会是
this.aspx?value1=5&value2=2&value3=3 - LinkTargetLocationModification
定义时，它的值会解释为一个目标位置（#targetLocation），改写或添加到链接的URL上。例如，如果LinkTo的URL在正常情况下是
this.aspx?value1=1&value2=2#target
并且LinkTargetLocationModification被设置为newtarget
结果链接URL将会是
this.aspx?value1=1&value2=2#newtarget
- LinkCssClass
应用到链接的CSS类（标签的class属性）
- LinkRel
- LinkTarget
- LinkTitleText/LinkTitleResourceName/LinkTitleResourceFile
应用到链接的标题（title）。如果同时定义了两者，LinkTitleResourceName将会覆盖LinkTitleText。
对这些属性的了解提供了关于所有单值/单对象控件的知识，它们都以同样的方式工作（大部分情况下都由它们的基类实现）。
我认为现在提供一个完整的Chameleon页面会很有帮助。我上传了默认的博客主页（postlist.aspx，查看文章底部来获取这个文件）。我建议你审阅这个简单的Chameleon页面，看看单值控件是怎么使用的——单值控件应该很容易认出来，因为它们通常都叫somethingDATA。
如果你有任何关于Chameleon的问题，请通过我的联系表单或添加评论发送给我。我会在这一系列的最后一篇文章里回答它们。
这个系列的下一篇文章里，我会讨论Chameloen列表控件。
