A Roll-Up of Fun & Lessons Learned Using the Content Query Web Part (CQWP) Sean SquiresProgram ManagerMicrosoft Corporation

ECMS310

Why is the CQWP so cool?Powerful web part for presenting and delivering data to one or more places from one or more places.

With careful site design, this roll-up web part facilitates a lot of content scenarios.

Use with tagging and targeting scenarios to display relevant data easily on pages throughout the siteAllows you to centralize the content in the presentation layer regardless of where it resides

Centralize Content Centralize DeliveryList 1

List 2

List 3

List 4

CQWP

CQWP 1

CQWP 2

CQWP 3

CQWP 4

List

And combined: rolling up multiple

lists across multiple web parts

Where we use it Microsoft Web (MSW)

Company portal Employees use MSW to find information, stay informed and make productive use of the intranet

MS Library (MSL)Library portal

Employee’s primary access point to business , marketing & technical research resources

HRWeb (personnel)

LCAWeb (legal)

InfoWeb (field sales)ITWeb (IT Help)

FinWeb (financial)

How we use itRolling up select items from single/multiple sources

Content Query

web part

Content Query

web part

Content Query

web part

Content Query

web part

How we use it: news roll-up

Re-using centralized content: custom queries are used to display updated & filtered views of items stored in libraries and lists w/o having to constantly edit pagesAutomatically building news archives pages by category and publish date w/o manual intervention

How we use it: content filtering

Use defined target and status site columns to enable content filtering and display

How we use it: data presentation

Ensuring consistent formatting/presentation across displays

Styles are defined according to portal brand guidelines

How we use it: content delivery

Use the CQWP RSS feature to emit a category-filtered stream of results from news listsUse the created URL on other pages to have more control over design and placement of RSS icon

How we use it: content targeting

Targeting select content to specific audiences, like FTEs:

Audiences can be defined by SharePoint or security groups, DLs, or rules-based entitiesAudience targeting is enabled under the Query tab and defined under the Advanced tab of the tool pane.

OOB Functional Considerations

The CQWP is part of the publishing features set so this will need to be activated for the web part to be available in the gallery.

NOTE: the part is not available in WSS.It can only query against single-value Lookup or Choice fieldsIt cannot query across site collectionsIt doesn’t support server-side pagination Unlike the Data View Web Part (DVWP) it can easily query across lists within the same site collection

Before you use start

Getting the most out of this web part requires consideration and planning of your content management needs up front

Design IA• Define

content organization and navigation needs

Plan Content Types• Define

your schema and filter fields

Determine Roll-ups• Define

scenarios and property tagging

Identify Display Fields• Define

styles

CQWP Usage on Microsoft Portals

demo

Anatomy of the CQWPIt uses property settings and CAML to construct the query and the SPSiteDataQuery class to query the SharePoint site to gather results. There are a lot of properties available for configuring and customizing the query

Fortunately, you don’t need to modify that many of them.To do these more advanced configurations requires modifying the file through file export or SharePoint Designer (SPD).

The web part uses three primary XSL files to render aggregated query results.

ContentQueryMain, ItemStyle, and Header.xslNOTE: A fourth XSL file is available for the RSS feed.

The default styles can render the following: Title, Description, LinkUrl, and ImageUrl.

Custom Field Configuration

Only a few properties are available directly through the tool pane.

To modify the additional properties export the .webpart file and modify in editor of choice, and then modify the .webpart file.

Once configured, you can re-import or even upload the modified file to the web part gallery

Export to Configure

Configure Content

Type

Add

CQWP

Export and Modify Properties•Alternately, edit in SPD

Import and Update Style Reference•Copy a desired style to use as a template

Pertinent Web Part Properties

•Additive property used to declare your custom fields when retrieving data. This property uses an internal name, display name syntax:•Title,Text;ID,Counter;Editor,User

CommonViewFields

•Used to rename a column after the data has been retrieved and before passing to transform•Useful for column name mapping to re-use existing XSL styles.

DataColumnRenames

There are only a few key properties we typically configure to expose and our custom content type fields.

These properties are used for data retrieval expansion

Pertinent Web Part Properties

•Allows the default query behavior to be overridden. •When this is used, the filtering/sorting/grouping functions of the tool pane are dimmed

QueryOverride

•Used to retrieve additional or specific lists. •When this property is used the list function of the tool pane is dimmed

ListsOverride

These properties override default behavior

Pertinent Web Part Properties

•Used to declare additional fields to be displayed in the filter fields pick list. This also follows the internal name, display name syntax

AdditionalFilterFields

•Used to declare additional group/sort fields to show in the tool pane.

AdditionalGroupandSortFields

These properties modify the web part UI only, not the behavior.

Demo

CQWP Configuration

Export to configure additional properties

Tips/Tricks: General

ALL XML inside a <property/> tag must be enclosed in a <![CDATA[ ]]> block.The default web part queries against all page libraries in a site collection.

Suggest either changing default to be opt-in instead of opt-out or ensure your site publishing rules accommodate this.

Upload to the web part gallery a pre-configured CQWP.

Expose custom fields via AdditionalFilterFields to allow for modification via browser

Tips/Tricks: General

Use CQWPs on a hidden page to emit RSS feeds whose URLs can be used elsewhere.Use consistent site columns for content filtering.If your content changes frequently keep the Cross List Query Cache Changes setting to check every time. If you need to query against >1000 lists you can add the MaxListLimit attribute to the ListsOverride property.

By default this is set to 1000There is a performance trade-off here

Tips/Tricks: Query ConstructionUse QueryOverride property for more complex

queriesThe CAML query can have any number of filter fields and values (tool pane is limited to three)CAML Query Schema Reference: http://msdn2.microsoft.com/en-us/library/ms467521.aspx

Using OffSetDays attribute to create a “moving window” (toolpane is limited to [Today] or a specified date<OrderBy><FieldRef Name="Modified" Ascending="FALSE" /></OrderBy><Where><Geq><FieldRef ID="Modified" Nullable="True" Type="DateTime"/><Value Type="DateTime"><Today OffsetDays="-45"/></Value> </Geq></Where>

Tips/Tricks: Query ConstructionUse QueryOverride property for more complex

queriesYou can only have up to two items w/in each <AND> in the <Where> clause:<OrderBy><FieldRef Name="ArticlePublishDate" Ascending="FALSE" /></OrderBy><Where><And><And><And><Geq><FieldRef ID="ArticlePublishDate" Nullable="True" Type="DateTime"/><Value Type="DateTime"><Today OffsetDays="-7"/></Value></Geq><Neq> <FieldRef ID="ArticlePublishDate" Nullable="True" Type="DateTime"/><Value Type="DateTime"><Today /></Value></Neq></And><Eq><FieldRef Name="PublishedIn" /><Value Type="Choice">Home Page</Value></Eq></And><Eq><FieldRef Name="HomePage" /><Value Type="Choice">Top Story</Value></Eq></And></Where>

Tips/Tricks: Query Construction

Use ListsOverride property to query against other list types

Only list templates available at the site root are enumerated. You can extract a list GUID from the list settings page (replacing %2D w/ a dash)<property name="ListsOverride" type="string"><![CDATA[<Lists><List ID="ea4738a5-0cd6-4ae9-beea-15c2e5e6397e"/></Lists>]]></property>

When setting properties requiring use of the column’s internal name remember a space is represented as _x0020_ :

<property name="CommonViewFields" type="string"> Project_x0020_Title, Text;Project_x0020_Owner, Text;ProjectNotes, Text</property>

Cross list query cannot filter on multi-value lookup or choice fieldsWhen filtering on Yes/No data type use the value “1” and not “1”

Tips/Tricks - Presentation

Add custom styles to existing XSL files to take advantage of built in functions and template structure

Careful to verify before publishing to ensure no malformed XSLXSL files need to be published for reader to view changes

Use the datacolumnrenames property to re-use styles

Eliminates need to create custom transformations for each custom dataset<![CDATA[<property name="DataColumnRenames" type="string">PostBody,Description</property>]]

Tips/Tricks - PresentationTo render HTML and not raw tags set the disable-output-escaping attribute to true:

<xsl:value-of select="@InternalName" disable-output-escaping="yes"/>

NOTE: potential security risk w/ this setting; be sure you trust content.XSL style useful for getting the internal name for a columns

<xsl:for-each select="@*">P:<xsl:value-of select="name()" /></xsl:for-each>

Referencing a Blog post:<a href="{substring-before(@LinkUrl,'/Pages')}/mslibraryblog/Lists/Posts/ViewPost.aspx?ID={@ID}"><xsl:value-of select="@Title" /></a>&#160;&#160;<xsl:value-of select="concat(substring(@PublishedDate,6,2), '/', substring(@PublishedDate,9,2), '/', substring(@PublishedDate, 1,4))" /> 

Other good references:Default Functions: http://msdn2.microsoft.com/en-us/library/bb447557.aspx Heather Solomon: http://www.heathersolomon.com/blog/articles/customitemstyle.aspx

Custom CQWP Examples

Modifications we’ve made to the OOB CQWP

Override Extension: show additional property fields in the tool paneDynamic Filtering: allowing overriding query w/ querystring parameterCarousel Display: tool pane options to present results in a rotating display.

Source code available on CodePlex: https://www.codeplex.com/Release/ProjectReleases.aspx?ProjectName=sptoolbox&ReleaseId=11150

Override Extension

Created an extended version with more properties exposed

Added a query override call to dynamically update same page contents based on URL parameters

<Query><Where><Contains><FieldRef Name=”MRVendor” /><Value Type=”Text”>{vendorname}</Value>

</Contains></Where></Query>

Content Carousel ExtensionCreated an extension to support a filmstrip display of returned results.A preliminary release that we’d like to do more with – we’ll keep the community posted.

demo

Custom CQWP: Property Override &Dynamic Filtering

Resources & Related Content

Office Visual How To: Displaying Custom Fields in CQWP in Office SharePoint Server 2007: http://msdn2.microsoft.com/en-us/library/bb850574.aspx

Configuring CBQ (ECM blog post, G. Perantatos): http://blogs.msdn.com/ecm/archive/2006/10/25/configuring-and-customizing-the-content-query-web-part.aspx

How to: customize the CQWP by using Custom Properties (MSDN article): http://msdn2.microsoft.com/en-us/library/aa981241.aspx

Building a News Workbench on MOSS 2007 (ECM blog post, S. Squires): http://blogs.msdn.com/ecm/archive/2008/02/19/building-a-news-workbench-on-moss-2007-part-1.aspx

Post Event DVD brought to you courtesy of:

SUBMIT AN EVALUATION

For a chance to win an 8GB ZUNE!Submit evaluations on

MySPC www.MicrosoftSharePointConferenc

e.com

© 2008 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries.

The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after

the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.