Catalog Item Reuse Web Part with RenderFormat added in a Page Layout
Catalog Item Reuse Web Part is the control that you have to use to display data from Managed Properties on your pages in search-driven publishing scenarios. And while everything might seem okay at first, it’s just the matter of time until you see your content rendered as plain-text.

Displaying content on pages yesterday

When working with publishing sites in SharePoint 2007 and 2010 if you wanted to display a value of field on a page, you had to use a publishing control. If you were editing content in-place you would use for example a TextField control:

<SharePointWebControls:TextField FieldName="Title" runat="server" />

An alternative for scenarios where content isn’t edited in-place is to use the FieldValue control, for example:

<SharePointWebControls:FieldValue FieldName="Title" runat="server" />

No matter which type of control you would choose to have your content displayed on the page, they both assume that the content is a part of the page that you are on. This isn’t however the case with SharePoint 2013 search-based publishing.

Displaying content on pages with SharePoint 2013 search-based publishing

One of the new capabilities of SharePoint 2013 is the search-driven publishing model, where the content is managed in an authoring site, indexed by SharePoint Search and then published in some other Site Collection, Web Application or maybe even Farm. Using template pages you can create category and item pages to have your content displayed, but if the content isn’t there, how do you display it on the page?

SharePoint 2013 introduces two new Web Parts to help us work with content in search-driven publishing scenarios. First there is the Content Search Web Part that is used for building content aggregations. The second one is the Catalog Item Reuse Web Part which is used as a replacement for Field Controls and which is used to display values of Managed Properties.

Using Catalog Item Reuse Web Part isn’t that complex and comes down to passing the name of the Managed Property of which the value you want to display using the SelectedPropertiesJson attribute:

<Search:CatalogItemReuseWebPart runat="server"
        UseServerSideRenderFormat="True"
        NumberOfItems="1"
        UseSharedDataProvider="True"
        SelectedPropertiesJson="[&quot;Title&quot;]"/>

In real-life scenarios however things can get a little more complicated.

Inconvenient Catalog Item Reuse Web Part and displaying content from Managed Properties

No matter which Managed Property you want to display, the Catalog Item Reuse Web Part is the control that you need to use. Managed Properties however can contain all kinds of data: from plain-text to HTML. So how does the Catalog Item Reuse Web Part know how to display the content properly?

How the Catalog Item Reuse Web Part guesses how to format content

When rendering the contents of a Managed Property, the Catalog Item Reuse Web Part tries to determine how that content should be determined. The way it work is that the Catalog Item Reuse Web Part analyzes the name of the Managed Property that you want to render. You might have noticed that many of the Managed Properties created automatically by SharePoint are named like: MyPropertyOWSTEXT. It’s exactly that last part (string after OWS) that the Catalog Item Reuse Web Part uses to determine how the data should be formatted. For automatically created Managed Properties the odds are high that SharePoint will do the right thing and render your content the way it should be rendered, but what to do with Managed Properties created manually that don’t necessarily are suffixed with OWS and type?

Formatting content with the Catalog Item Reuse Web Part

By default the Catalog Item Reuse Web Part renders its contents as text where all of the HTML is escaped. So if you would for example create a Managed Property called PublishingImage mapped to the standard SharePoint PublishingRollupImage Site Column and have it displayed on a page using the Catalog Item Reuse Web Part without providing any format, like:

<Search:CatalogItemReuseWebPart runat="server"
        UseServerSideRenderFormat="True"
        NumberOfItems="1"
        UseSharedDataProvider="True"
        SelectedPropertiesJson="[&quot;PublishingImage&quot;]" />

What you would get is very likely not what you wanted:

Escaped HTML instead of the picture displayed in the web browser

As you can see, instead of having the image displayed all we have is the escaped HTML of the img tag.

To work around this issue the Catalog Item Reuse Web Part allows you to specify the type of the data yourself using the RenderFormat property. Despite its name it doesn’t really allow you to format the rendered content. All it does is allowing you to provide the type of the data stored in the Managed Property.

The Catalog Item Reuse Web Part supports different rendering mechanism for the following types of data:

  • DateTime
  • Integer/Number
  • Currency
  • Boolean
  • User
  • Taxonomy
  • URL
  • HTML

To specify which data type you want to use you have to provide the name of the type as XML:

<Search:CatalogItemReuseWebPart runat="server">
    <RenderFormat>
        <Format Type="HTML" />
    </RenderFormat>
</Search:CatalogItemReuseWebPart>

For some of types additional formatting parameters can be specified:

  • DateTime: DateOnly (true to render the date only), eg.
    <DateOnly>true</DateOnly>
  • Integer/Number: DecimalPlaces (number of decimal places)
  • Currency: Currency (true to render a number as currency)
  • URL: Picture (true to format the URL as a picture; surrounds the URL with the img tag)

Those parameters should be then included as a child node of the Format element, eg.:

<Search:CatalogItemReuseWebPart runat="server">
    <RenderFormat>
        <Format Type="DateTime">
            <DateOnly>true</DateOnly>
        </Format>
    </RenderFormat>
</Search:CatalogItemReuseWebPart>

So if we set the RenderFormat property to render our image to HTML, like:

<Search:CatalogItemReuseWebPart runat="server"
        UseServerSideRenderFormat="True"
        NumberOfItems="1"
        UseSharedDataProvider="True"
        SelectedPropertiesJson="[&quot;PublishingImage&quot;]">
    <RenderFormat>
        <Format Type="HTML" />
    </RenderFormat>
</Search:CatalogItemReuseWebPart>

We would get our image displayed correctly as expected:

Image from a Managed Property displayed correctly using the Catalog Item Reuse Web Part

Summary

Catalog Item Reuse Web Part is a new control that SharePoint 2013 offers to display content on pages in search-driven publishing model scenarios. While this control works as expected for Managed Properties created automatically by SharePoint, it renders the contents of manually created Managed Properties as plain-text. Using the RenderFormat property you can specify what kind of data the particular Managed Property is holding and how it should be rendered.