Thursday, September 17, 2015

Customize a Content Query Web Part in SharePoint 2013

A Content Query Web Part (CQWP) can be used to rollup information from other locations within the same site collection. For example, you can use this web part to display list items from a list in a sub-site that is a sibling of the current site. Or, you could use it to display all calendar items from sites within the site collection. Out-of-the-box, this web part includes several preconfigured views and formatting options. But, what happens when you need to customize how information is displayed? This article walks you through the steps of customizing the CQWP web part to add additional list fields and labels to the web part output.

1.       Start by creating a new page and adding the CQWP web part to the page.



2.       Next, from the web part menu, select Export … and save the web part to your desktop.



3.       Use your favorite text editor to open the exported web part file and find the following line:

<property name="ItemXslLink" type="string" />

And change it to:

<property name="ItemXslLink" type="string">/<path>/Style Library/XSL Style Sheets/CustomItemStyle.xsl</property>

(The URL is the relative path to the XSL Style Sheets directory in the Style Library at the root of the site collection parent.)

4.       Save the file.

5.       Delete the existing web part from your page and upload the new custom web part by selecting Upload a Web Part and then clicking the Upload button.



6.       The customized web part will appear under Imported Web Parts. Add the new custom web part to the page.



7.       The next step is to create a custom style sheet to add extra slots to the web part. To do this, open the site collection parent in SharePoint Designer and navigate to All Files>Style Library>XSL Style Sheets.

8.       Create a copy of the ItemStyle.xsl stylesheet and rename it CustomItemStyle.xsl (this is the name we assigned in Step 3).

9.       Check out the CustomItemStyle.xsl and open it as XML from SharePoint Designer. There are several different styles preconfigured in the web part. Determine which style is most similar to the look and feel you wish to achieve and then look for the name in the xsl:template name tag. Most of the names are similar to the menu options under item style in the CQWP Presentation section. In this example, I will copy the Title and Description template, which is named “NoImage”. (I know? Right? This makes no sense. But, here’s a hint, the templates in the style sheet appear in the same order as the choices on the web part menu).



10.   Now, copy everything between the <xsl:template></xsl:template> tags and paste it after <xsl:template>. We will now modify the copied template section to add a new Item Style option to the web part menu and to add “slots” to the Fields to Display section of the web part.

11.   Find the following line in the copied section:
<xsl:template name="NoImage" match="Row[@Style='NoImage']" mode="itemstyle">

12.   Replace NoImage with “Custom” so that your new line looks like this:
<xsl:template name="Custom" match="Row[@Style='Custom']" mode="itemstyle">.

13.   Now, we are going to add slots to the Fields to Display area. Copy the Div class for description and paste it under the </div> closing tag.

<div class="description">
<xsl:value-of select="@Description" />
</div>

14.   Repeat step 13 for each additional slot that is to be added.

15.   Next, update each class and each value-of select value to a unique name. In this example, we will create four slots and name them Custom1, Custom2, Custom3, and Custom 4. Each Div section will look something like this:
 
<div class="Custom1"><xsl:value-of select="@Custom1" />
</div>
 
16.   Now we will add some labels to the slots we created so that the data is displayed in a way that is appealing to the eye. First enclose the Div tags that will include labels in <p> tags. Then, after the <div class=”Custom1”> tag, add a custom label with html formatting:

<p>
<div class="Custom1"><b>Priority: </b><xsl:value-of select="@Custom1" />
</div>
</p>

17.   After you have completed adding all the labels you need, your code should look something like this:



<xsl:template name="Custom" match="Row[@Style='Custom']" mode="itemstyle">

        <xsl:variable name="SafeLinkUrl">

            <xsl:call-template name="OuterTemplate.GetSafeLink">

                <xsl:with-param name="UrlColumnName" select="'LinkUrl'"/>

            </xsl:call-template>

        </xsl:variable>

        <xsl:variable name="DisplayTitle">

            <xsl:call-template name="OuterTemplate.GetTitle">

                <xsl:with-param name="Title" select="@Title"/>

                <xsl:with-param name="UrlColumnName" select="'LinkUrl'"/>

            </xsl:call-template>

        </xsl:variable>

        <div class="item link-item">

            <xsl:call-template name="OuterTemplate.CallPresenceStatusIconTemplate"/>

            <a href="{$SafeLinkUrl}" title="{@LinkToolTip}">

              <xsl:if test="$ItemsHaveStreams = 'True'">

                <xsl:attribute name="onclick">

                  <xsl:value-of select="@OnClickForWebRendering"/>

                </xsl:attribute>

              </xsl:if>

              <xsl:if test="$ItemsHaveStreams != 'True' and @OpenInNewWindow = 'True'">

                <xsl:attribute name="onclick">

                  <xsl:value-of disable-output-escaping="yes" select="$OnClickTargetAttribute"/>

                </xsl:attribute>

              </xsl:if>

              <xsl:value-of select="$DisplayTitle"/>

            </a>

               <p>

               <div class="description">

                <b>Description: </b><xsl:value-of select="@Description" />

            </div>

            <div class="Custom 1">

            <b>Priority: </b><xsl:value-of select="@Custom1" />

            </div>

               <div class="Custom 2">

               <b>Owning Application: </b> <xsl:value-of select="@Custom2" />

            </div>

            <div class="Custom 3">

               <b>Reporting Tool: </b> <xsl:value-of select="@Custom3" />

            </div>

                     <div class="Custom 4">

                <xsl:value-of select="@Custom4" />

            </div>

             </p>

        </div>

    </xsl:template>

18.   Save the file and check it in.

19.   Now return to the page where you added the CQWP and refresh the page. Next, edit the web part. The new template should appear on the list of Item Styles and the new slots should be in the Fields to Display section.

20.   Select the new Custom template from the Item Style menu and then add the internal field name of each field you wish to display followed by a semi-colon in the new custom field slots.

21.   Set other formatting options as desired, then click Apply and OK.



22.   In the following screenshot, items were queried from a list in a sibling site to the current site. Presentation was set to group items by the “Report Repository ID” field and items were sorted by Created date. The Banded Group Style was selected and the Custom Item Style was selected. The built in Title and Description slots were used and three custom columns were populated in the new slots added to the style sheet.