[译]SharePoint 2007 SDK:使用属性来自定义内容查询WEB部件

 

1.1如何：使用属性来自定义内容查询WEB部件

使用内容查询WEB部件可以去创建从多个数据源获取数据的用户统一视图。当你添加一个内容查询WEB部件到一个WEB页面后，你可以通过设置用户属性来自定义WEB部件的查询行为、自定义列表和内容类型。对于ContentByQueryWebPart类来说有60个属性和方法可用，它们中的很多是可以自定义的。本章介绍了很多属性，包括其结构和CAML格式的用法示例。

有各种不同的方式去理解内容查询WEB部件自定义属性。他们是MOSS 2007从WSS3.0继承过来的或是独特的MOSS 2007属性。本章把重点放在MOSS 2007的属性上，它们可以有两个基本的分类：

Ÿ   设置或重写WEB部件的底层行为方面的属性。某些情况下，他们也影响界面。

Ÿ   不通过设置或是重写底层动作来修改WEB部件界面的属性。

在第一个分类中的属性，比如重写，一般来说更强大。因为你可以通过使用它们来修改WEB部件的功能。如果当用户试着去修改界面或是设置另一个属性来影响这个属性的所决定的功能时，这个属性将在界面中“取胜”。这就意味着：这个属性重写了其它设置并决定了内容查询WEB部件功能。当你想做如下的事情时，这些属性更强大：

Ÿ   添加内置字段和字段参数

Ÿ   重写默认的跨列表查询行为以便通过UI界面来修改字段和字段参数时不被覆盖或是被其它更改破坏。

Ÿ   重命名长、复合栏名到更通用XSLT变量名称，而不需要给每一个Schema都创建自定义的XSLT。

修改UI和行为的属性列表：

属性	描述
CommonViewFields	请求的其它必要的字段，因为内容查询WEB部件不会自动地返回所有的字段，所以如果你想去在XSLT中渲染他们的话，你需要去请求访问字段。 这个属性是复合型，这意味着你可以增加多个“普通视图字段”到内容查询WEB部件并且扩展它的基本属性，比如FieldDescription(字段描述)和FieldTitle(字段标题)
QueryOverride	忽略对于内容查询WEB部件UI界面的设置限制。指定CAML跨列表查询。 当这个属性被设置时，UI界面的筛选器、排序和分组在工具面板里就会失效。比如，默认情况下内容查询WEB部件允许三个筛选器，你可能想要添加更多的以保证自定义字段和行为继续存在UI界面中。
WebsOverride	决定是否跨列表查询是否可以递归子网站。默认情况下MOSS2007的查询会覆盖子网站，父站点和它的子站点内容都会被显示。 当这个属性被设置成内容查询WEB部件不会覆盖子网站，只从特定的网站显示查询结果。
ListsOverride	在MOSS2007重写列表行为并且支持多种类型的列表，比如页面库、普通列表类型和指定列表类型。你可以使用自定义属性去设置任务一个列表类型，甚至那些不在UI界面中列举的，因为那些模板不一定在根位置定义或是一个基本的类型。 在WSS3.0SDK中，列表类型定义在reference节的列表元素（List Element）中。
ViewFieldsOverride	除了MOSS 2007自动获取的基本的字段外，给内容查询WEB部件从指定查询中查询一系列附加字段的功能，。
DataColumnRenames	给内容查询WEB部件在数据传递到XSLT渲染前重命名栏的功能。

另外，更简便的方式就是在页面界面中来设置字段、分组和排序选项和筛选器。这些设置不会在WEB部件的内部行为起作用而且可以被在第一种方式的属性所覆盖。这种方式一般使用在如下情况比较有用：在当一个内容查询WEB部件实例被加到页面上，而你想通过此来提供这个WEB部件的初始设置；只设置单个WEB部件的属性，而不用重写；或是给最终用户提供更多的可用设置选项。

属性	描述
其它筛选字段AdditionalFilterFields 其它分组和排序字段AdditionalGroupAndSortFields	包括一个或者多个其它字段（AdditonalFilterFields属性）或是不是通常显示在UI界面在筛选下拉列表中的分组和排序选项（AdditionalGroupAndSortFields属性），这在如下情况下比较有用：如果某个显示在某些列表库中的字段不准备作为一个网站栏，但是你希望这个字段可以在UI设置界面中可见。当这个属性被设置时，UI界面提供这个栏用来进行筛选。
筛选字段1FilterField1 筛选类型1FilterType1 筛选值1FilterValue1 筛选操作1FilterOperator1 筛选逻辑关系 Filter1ChainingOperator	你可能想去筛选UI支持以外的值。使用这些属性去预填充一些UI的值，比如当WEB部件第一次被添加到页面中去。例如，你可能想要设置一些默认的值，以便在与今天有关系的数据集中去进行筛选操作。

有不止一种的方法去设置或是修改内容查询WEB部件的自定义属性，目标、你在网站的位置和网站设计过程决定了你采用哪种方式。例如，如果你正在自定义一个页面布局，你可能想要使用SPD2007在你自定义页面布局时来自定义内容查询WEB部件。如果你正在创建一个新的自定义的内容查询WEB部件，你可能想去使用SPD来当你正在创建一个新的内容查询WEB部件给一个已存在页面布局时来添加或是修改自定义属性。

如果你想去修改已存在的内容查询WEB部件的自定义属性，你可以导出.webpart文件，复制它然后重命名原文件，在重命名的.webpart文件中来修改自定义属性，然后把它导入到你页面上的一个WEB部件区域。

导出一个.webpart文件，设置自定义属性然后导入

1. 登录WEB网站，在“网站设置”菜单中选“编辑页面”。

2. 在页面中找到内容查询WEB部件，然后在“编辑”菜单中选择“导出”。

3. 保存成.webpart文件。

4. 重命名这个.webpart文件，然后使用记事本或是SPD2007打开这个已重命名的文件。

注意：

重命名原始的.webpart文件要保证一个原件的副本，以在未来考虑升级时导入。

1. 添加或修改属性和属性值。

2. 保存更改。

3. 从“页面”菜单，指向“添加WEB部件”然后选择“浏览”。

4. 从WEB部件列表中选择你想导入的WEB部件，然后单击“确定”。

5. 把这个WEB部件拖到页面的WEB部件区域中。

示例

这一小节描述了自定义属性其中包括格式化代码示例、CAML查询。首先，我们介绍格式化、基本的字段信息和使用CommonViewField(普通视图字段)属性的技巧。其次，我们展示一个完整的CAML查询然后设置QueryOverride, ListsOverride, WebsOverride, and ViewFieldsOverride属性。你可以添加在CAML查询中每一个属性值到.webpart文件的<property value>标记代码中。最后，向你展示一下DataColumRenames属性和筛选、分组、排序的相关属性。

CommonViewFields(普通视图字段)属性

当自定义这个属性的时候，你可以使用两个格式。一个是通过字段的内部名称或是同时通过内部名称和字段的类型。格式如下：

Ÿ   内部名称

Ÿ   内部名称,字段类型

“内部名称,字段类型”，这种格式是最普遍的格式。

MOSS 2007使用内部名称在应用程序中来唯一标识某个字段。内部名称在此处的用法完全不同于在UI界面中使用的字段名称。比如，内部名称通过_X0020_来表示空格。你可以通过在网站栏页面查看查询字串参数看见内部名称，或是通过查看导出的WEB部件的.webpart文件的代码。

WSS3.0的SDK里有SPFieldType枚举成员显示了字段的所有类型。除此以外，MOSS 2007包括四个其它的HTML, Image, Link, 和 SummaryLink。以上的类型CommonViewField都能包括。

你也可以把CommonViewField定义成复杂的表达式，如果你想去设置更多的字段在。使用分号“；”如下格式：

内部名称;内部名称,字段类型

CommonViewfields是一个附加的属性，这就意味着你能添加一个普通视图字段在内容查询WEB部件的基本字段之上。内容查询WEB部件的基本字段在UI显示为网站栏名称。如下的表格列举了基本字段名称和类型：

名称	类型
标题Title	Text
文件FileRef	Lookup
ID	Counter
修改时间Modified	DateTime
作者Author	"User"
修改者Editor	User
创建时间Created	DateTime
滚动图象 PublishingRollupImage	Image
级别Level	"Number"
内容Note	"Note"

在这个示例里，CommonViewFields属性标记里设置了GUID， GUID是MOSS2007内部使用去引用字段的内部名称、字段类型。

<property name="CommonViewFields" type="string">_Level,Number;PublishingRollupImage;</property>

QueryOverride, ListsOverride, WebsOverride, 和 ViewFieldsOverride 属性

重写类属性：QueryOverride, ListsOverride, WebsOverride, 和 ViewFieldsOverride，每一个重写一个默认的内容查询WEB部件的行为。要重写一个行为，必须构建一个定义了给定条件的CAML查询。

注意:

如果要学习更多的CAML语法和命令，可以在WSS 3.0的SDK里面找CAML参考一节。

在这个示例中，描述了通过CAML查询来设置自定义属性。这个CAML查询的功能是：查询一个已有字段；查找过去7天内被修改的列表项并把结果按照倒序排列；指定了列表的类型；指定了网站和它的子网站；指定了显示的字段。

全部查询如下：

1    <ViewFields>

 2   <FieldRef Name="Title" Nullable="True" Type="Text"/>

 3   <FieldRef Name="Comments" Nullable="True" Type="Note"/>

 4 </ViewFields>

 5 <Lists ServerTemplate="850"></Lists>

 6 <Webs Recursive="True" />

 7 <RowLimit>15</RowLimit>

 8 <Query>

 9    <Where>

10     <Gt>

11       <FieldRef Name="Created" Nullable="True" Type="DateTime"/>

12       <Value Type="DateTime"><Today OffsetDays="-7"/></Value>

13     </Gt>

14   </Where>

15   <OrderBy>

16       <FieldRef Name="Created" Nullable="True" Type="DateTime"

17       Ascending="FALSE"/>

18   </OrderBy>

19 </Query>

QueryOverride property(查询重写属性)

其中8到10行定义了查询重写的属性

8     <Query>

 9    <Where>

10     <Gt>

11       <FieldRef Name="Created" Nullable="True" Type="DateTime"/>

12       <Value Type="DateTime"><Today OffsetDays="-7"/></Value>

13     </Gt>

14   </Where>

15 <OrderBy>

16    <FieldRef Name="Created" Nullable="True" Type="DateTime"

17    Ascending="FALSE"/>

18 </OrderBy>

19 </Query>

在上面的代码中：

Ÿ   7至9行定义了查询并开启了<where>子句

Ÿ   10行引用个了一个基本类型字段Created（创建时间），它的类型是日期时间型。

Ÿ   11行设置了这个日期时间类型字段的值，这个值比Today(今天)要前推7天。

Ÿ   12行和13行闭合<Where>子句。

Ÿ   14行开启了<OrderBy>子句，决定了查询的排序方式。

Ÿ   15行和16行把排序字段设置为“Created”（创建时间）。WEB部件会按这个字段来倒序显示数据。

ListOverride 属性（列表重写属性）

你也可以使用CAML查询去从WSS 3.0和MOSS 2007的列表中查询列表项。如下的表格说明了不同列表类型查询的CAML的表达式：

列表类型	属性表达式
页面库	[xml] <![CDATA[ <Lists ServerTemplate="850"> </Lists> ]]>
通用列表类型	[xml] <![CDATA[ <Lists BaseType="0"> </Lists> ]]>
特定的列表类型	[xml] <![CDATA[ <Lists> <List ID="{fa564e0f-0c70-4ab9-b863-0177e6ddd247}"/> </Lists> ]]>

在示例中，第5行定义了列表重写(ListVoverride)属性：

5 <Lists ServerTemplate="850"></Lists>

在这种情况下，这个查询使用了ServerTemplate=”850”去重写当前正在使用的列表。在WSS3.0的SDK的Lists属性主题里，你可以找到可用列表的一系列类型。

WebsOverride属性（子网站递归重写属性）

你可以使用CAML去设置WebsOverride属性，去查询包括子网站在内的所有数据。

<![CDATA[

   <Webs Recursive="True"/>

]]>

或是只查询特定网站的数据：

<![CDATA[

   <Webs/>

]]>

在示例的第6行，我们设置去递归查询包括子网站的项目。

6 <Webs Recursive="True"/>

ViewFieldsOverride属性（视图字段重写）

如果你想显示WEB部件中某个项的多个值，你要设置ViewFieldsOverride属性去获取特定类型的数据。

<![CDATA[

   <FieldRef Name="Comments" Nullable="True" Type="Note"/>

   <FieldRef Name="Created" Nullable="False" Type="User"/>

]]>

注意：

设置 Nullable="True" 的作用是：当没有此栏时也照常返回查询的项。在此示便中,行 1–4 设置了 ViewFieldsOverride属性：

1 <ViewFields>

2   <FieldRef Name="Title" Nullable="True" Type="Text"/>

3   <FieldRef Name="Comments" Nullable="True" Type="Note"/>

4 </ViewFields>

Ÿ   第一行开启<ViewFields>子句，用来对ViewFieldsOverride属性进行重写。

Ÿ   第2行和第3行引用Title（标题）字段，这是一个单行文本字段，和一个Comments(说明)字段,这是一个多行文本字段。

Ÿ   第4行闭合<ViewFields>节。

DatacolumnRename属性（数据栏重命名）

为了可以自动地重命名栏，可以设置DatacolumnRename属性。这个属性是非常有用的当你想去最小化 XSLT和schema定义或是当你需要进行栏重命名的时候。比如，你可能想去重命名一个复合的栏名比如KBArticleTitle（知识库文章标题）为一个普通的XSLT变量名称，比如Title(标题)，然后就不需要去给每一个自定义schema去创建XSLT。

栏重命名是被逗号“，”分隔的，如下的格式：原名称，新名称：

<property name="DataColumnRenames" type="string">KBArticleTitle,Title</property>

注意:

如果你重命名一个栏，但这个新名称已经存在，此重命名行为无效。

Additional Field, Filter, Grouping, 和 Sorting Options（附加字段、筛选、分组和排序选项）

设置附加字段、筛选、分组和排序选项的属性，你能通过内部名称，GUID或是复合的内部名称、显示名称或是GUID来指定字段。

定义AdditionalFilterFields和AdditionalGroupAndSortFields属性，可以通过使用如下一种格式：

Ÿ   内部名

Ÿ   内部名,显示名

Ÿ   GUID

Ÿ   GIUD,显示名

你也能把AdditionalFilterFields和AdditionalGroupAndSortFields的定义组合成一个复合的表达式，这个表达式会更有用，当你想去设置多于1个字段时。使用分号“；”去分隔字段，比如：

内部名；GUID；内部名，显示名；GUID，显示名

通过设定AdditionalFilterFields属性，你能添加一个已有的筛选字段到UI界面中去：

<property name="AdditionalFilterFields" type="string">Created</property>

通过设定AdditionalGroupAndSortFields属性，你可以添加一个已有的选项到分组和排序的UI下拉列表中去。

<property name="AdditionalGroupAndSortFields" type="string">Created</property>

Filter 属性（筛选属性）

你可以自定义属性去扩展UI所支持的筛选值。设置或是修改任何筛选字段，筛选类型，筛选值或理筛选操作属性，添加或是改变UI界面的筛选行为。

注意：

筛选属性不会重写UI，而使用默认的值来预填充的UI

筛选字段、筛选类型和筛选值属性都是字符串类型：

Ÿ   <property name="FilterField1" type="string" />

Ÿ   <property name="FilterType1" type="string" />

Ÿ   <property name="FilterValue1" type="string" />

Ÿ   <property name="FilterOperator1" type="Microsoft.SharePoint.Publishing.WebControls.ContentByQueryWebPart+FilterFieldQueryOperator, Microsoft.SharePoint.Publishing, Version=12.0.0, Culture=neutral" PublicKeyToken=71e9bce111e9429c"/>

如下的例子，“日期时间”型筛选器，显示2006年10月25日后以后创建的项：

Ÿ   <property name="FilterField1" type="string">Created</property>

Ÿ   <property name="FilterType1" type="string">DateTime</property>

Ÿ   <property name="FilterValue1" type="string">Today-7</property>

Ÿ   <property name="FilterOperator1" type="Microsoft.SharePoint.Publishing.WebControls.ContentByQueryWebPart+FilterFieldQueryOperator, Microsoft.SharePoint.Publishing, Version=12.0.0, Culture=neutral" PublicKeyToken=71e9bce111e9429c"/>

在筛选操作和筛选逻辑关系使用如下的格式去设置类型参数：属性名称,命名空间,版本,语言,公钥

Ÿ   <property name="FilterOperator1" type="Microsoft.SharePoint.Publishing.WebControls.ContentByQueryWebPart+FilterFieldQueryOperator, Microsoft.SharePoint.Publishing, Version=12.0.0, Culture=neutral" PublicKeyToken=71e9bce111e9429c"/>

Ÿ   <property name="Filter1ChainingOperator" type="Microsoft.SharePoint.Publishing.WebControls.ContentByQueryWebPart+FilterField, Microsoft.SharePoint.Publishing, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c">Eq</property>

筛选操作的值和筛选关系的值，他们的属性是不一样的：

Ÿ   筛选操作属性在UI界面里列出的是“And”和”Or”。

Ÿ   筛选关系把筛选的字段和值联系在一起,位置位于UI界面中的，附加筛选，下的“显示如下的项”的第二个字段。

本表提供了筛选操作支持的值：

值	显示
And	And
Or	Or

本表提供了筛选关系支持的值：

值	显示
Eq	is equal to         （等于）
Neq	is not equal to（不等于）
Gt	is greater than（大于）
Geq	is greater than or equal to（大于等于）
Lt	is less than（小于）
Leq	is less than or equal to（小于等于）
BeginsWith	begins with（开始于）
Contains	Contains（包含）