Catalogs and Cross-Site Collection Publishing

A core component of Cross-Site Collection Publishing is catalogs. What exactly do we mean by catalogs? Catalogs, as used by Cross-Site Collection Publishing, can be any SharePoint list or library that will be shared across site collections. A list or library is configured as a catalog by being set as a shared catalog via a particular list’s List settings. Pages libraries, lists, and asset libraries must be configured as catalogs to be able to reuse content across site collections.

Once a catalog has been shared, a consuming site can connect to it by using the Catalog Connections setting found under Site Site Administration Manage Catalog Connections. Then by using search-driven web parts and specific queries to retrieve items from a given catalog result source, the consuming web site can display content as needed. This content can also be rendered via special pages that are automatically created by SharePoint called category and category item pages. The category page displays the catalog items when a user clicks on an item; it is displayed using the category item page. SharePoint also creates a category page layout and category item layout automatically at the time of connecting to a shared catalog.

Introduction to the Content Search Web Part

As we mentioned, the catalog contents are consumed via the new Content Search web part, which are placed on any given page within a publishing site. The Content Search web part is extremely powerful and contains a configuration panel to highly customize the queries as shown in Figure 8-2; one can test queries instantaneously to ensure results are returned and can easily configure refiners, sorting, and other query settings.

Overview of Display Templates

Because Cross-Site Collection Publishing depends on search and search results, a method is needed to control how search results get displayed on a given page. Display templates allow for custom rendering of search-driven content that resides in the result source created automatically by SharePoint when connecting to a shared catalog. SharePoint comes with several display templates that generally meet our needs. However, when branding a SharePoint site, there is a high likelihood a custom one will need to be created to display items branded appropriately. See the section “Applying Branding to Search Results with Display Templates” later in this chapter to learn how to create and brand your own display templates.

Another way to look at display templates is in the context of how we used to surface indexed data in SharePoint 2010, that being the Content Query web part. If you have used the Content Query web part in SharePoint 2010 (it is still available in SharePoint 2013), then you might have worked with the XSLT style sheets that the Content Query web part relied on to display query results. Display templates in Design Manager seek to replace XSLT, which few developers ever learned, with more standard HTML. We get into the specifics of creating display templates later in this chapter as well as in Chapter 9, as Cross-Site Collection Publishing and display templates are at the heart of the new WCM paradigm in SharePoint 2013.

There are two kinds of components that help render catalog contents via the Content Search web part. There is a Control display template, which handles the rendering of the entire filtered result, and an Item display template, which renders each individual item. These two templates are set in the web part tool pane as shown in Figure 8-3.

You can find the out-of-the-box display templates in the Master Page Gallery in a folder called Display Template. You also can browse to ∼sitecollection/_layouts/15/DesignDisplayTemplates.aspx, i.e. http://spectergroup.com/_layouts/15/DesignDisplayTemplates.aspx, in a browser for a list of all display templates. In addition to selecting the display templates, the Content Search web part allows you to specify the metadata or managed properties you would like to display. In this chapter’s walkthrough you will learn how to surface your own metadata and display it using your own look and feel.

Tagging Terms and Metadata

Items in a catalog must be tagged with metadata or terms. Once crawled, the search index adds this metadata, which can then be used in the consuming site collection via the Content Search web part configuration pane. In addition, a term set field can be used for managed navigation in the consuming site.

It is worth nothing that SharePoint 2013 automatically creates managed properties for site columns that are part of the metadata contained within a catalog. Also all managed properties that are automatically created are of type Text. There is a specific format SharePoint uses when it automatically creates managed properties. Table 8-3 shows the naming conventions.

Add a Suggested Browser Location

As stated earlier, while authoring content, users need the ability to pick media assets. We can leverage suggested browser locations on the Authoring Site so that content authors are able to easily pick media assets via the SharePoint Asset Picker modal window.

To add a suggested location, navigate to the Site Settings page on the main site of the authoring site collection and follow these steps:

1. Under Site Collection Administration, click Suggested Browser Locations to load the Suggested Content Browser Locations page.
2. Click New item to open the new form page.
3. Provide a display name, URL, and optional description of the suggested browser location, as shown in Figure 8-6.

   

   Figure 8-6. The configured suggested browser location on the authoring site

4. Click Save to save the suggestion location.

Configuring Catalog Sharing for Integration with Managed Navigation

The blog posts are authored on a subsite within the authoring site collection. This is also the Cross-Site Collection Publishing example we use to integrate with managed navigation. One of the key requirements from Specter Group was to have an image for each blog post. We simply add the existing site column Page Image, which is also used on publishing pages, but most certainly can be used on our blog post. Our first step is to configure the catalog. To accomplish this, follow these steps while on the authoring blog subsite.

1. On the authoring site, go to Site Settings Site Content. When the Site Content loads, hover over the right side of the blog library and click the ellipsis. Then click Settings.
2. Under General Settings, click Catalog Settings.
3. Select the Enable this library as catalog check box.
4. Under Anonymous Access, enable anonymous access.
5. Under Catalog Item URL Fields, select the ID field (this is the best option as it is unique).

Connecting to the Catalog with Managed Metadata Navigation

Now that we’ve configured our shared catalogs within our authoring portal, we next configure the connection to these catalogs for use by the Specter Group public web site.

Catalog connections are managed at the site collection level. On the content consuming site (i.e., the public site), follow these steps.

1. Go to Site Settings and under Site Administration, click Manage Catalog Connections.
2. Click Connect to Catalog. Refer to Figure 8-16, which shows the available catalogs. Notice the Blog - Posts and Specter Authoring Portal - Pages catalogs.

   

   Figure 8-16. The available Blog - Posts catalog previously set up on the authoring portal is shown on the Specter public web site

3. To the right of the catalog to which you wish to connect, in this case, Blog - Posts, click Connect.
4. You can now configure the connection. Refer to Figure 8-17, which shows the first two options, in particular how to integrate the connection and how the navigation hierarchy should be configured.

   

   Figure 8-17. Blog catalog connection configuration shows the first two options: connection integration and navigation hierarchy

5. Under Connection Integration, select the Integrate the catalog into my site option because we are looking to be able to navigate blog posts driven by the categories. When this option is selected, there are many options that can be configured and we walk through those in the next steps.
6. Under Navigation Hierarchy, ensure the metadata column Blog Category is selected in the drop-down list. The root term of the hierarchy is automatically selected for you. It is the one previously configured on the global term set. You do not want to include this root term on the site navigation if you already have a local term on your site navigation. In our case, in Chapter 6 we added the term “blog” to the navigation menu, so we would leave the Include root term in site navigation check box unchecked.

    Tip   If you choose to include the root navigation node, SharePoint automatically creates the site navigation. You can then change the order under the Site Settings Navigation. For an in-depth look at new navigation features, see Chapter 6.

   Once this configuration option is in place, the terms from the global term set labeled “Blog” will be shared with the local site navigation node labeled “Blog” and will appear with a pin icon in the Term Store Management Tool, as shown in Figure 8-18.

   

   Figure 8-18. Blog Post category terms pinned to the Site Navigation Blog term set

   The next configuration is Navigation Position. This option is extremely useful in our case, as the Specter Group public web site already contains a managed navigation node named Blog.

7. Our objective is to drop the blog categories under this node and allow for browsing the posts by category. Therefore, select the Select an alternate location in site navigation option as shown in Figure 8-19, and browse or type the name of the node you wish to drop the categories under. The intellisense should pick up the site navigation Blog node so you can select it.

   

   Figure 8-19. Navigation position allows flexibility in integrating the Catalog Navigation and positioning it exactly where we need to, in our case the Blog existing global navigation node

   The next important aspect of configuring the catalog connection is the Catalog Item URL Behavior and Catalog Item URL Format shown in Figure 8-20. Both are equally important.

   

   Figure 8-20. The Blog Catalog URL behavior and format configuration settings

8. Because we do not want users to browse to the authoring portal when clicking on a blog post, proceed to configure the Catalog Item URL Behavior and select the Make URLs relative to this site option.
9. For Catalog Item URL Format, select the second option to construct the URL based on the catalog properties and select the ListItemID field. This field is the unique identifier for a particular blog post. You will notice the URL preview underneath, which tells us how our navigation will look based on the original terms selected. In our case, this is the public site base URL followed by the Blog term root followed by the selected Category followed by the ID of the blog post.

Now that we have connected to our blog catalog, we see the dynamic navigation under the global site navigation with each blog category underneath the original blog node as the label (shown in Figure 8-21). You will also notice how SharePoint automatically builds a breadcrumb based on the selected blog category.

Using the Category and Category-Item Pages

When we create a connection to any catalog, SharePoint has the capability to create two key pages that are used to browse the catalog. These two pages are the category page and the category-item page. In addition to these two pages, two corresponding page layouts are provisioned and the category and category-item pages are created based on these layouts. In the example from the previous section, with our blog catalog, SharePoint automatically created page layouts named Category-Blog.aspx and CatalogItem-Blog.aspx as shown in Figure 8-22 at the time when we connected to the catalog.

We have the ability to customize these pages at various levels. We can customize the page layout or we can choose to only modify the page for a specific category. In Figure 8-23 you can see the modal dialog box that is displayed when a new category page is created.

Changing Metadata Displayed on a Category Page

By default, a category page might not display all of the metadata your scenario requires. In our scenario, the blog metadata displayed by default on the catalog consuming page is not enough. The category page only displays the image and title (see Figure 8-21). How about if you would like to display additional metadata such as the following:

• Title
• Body text
• Picture
• Published date
• Published by
• Comment count

To change what metadata is displayed you can edit the category page template or page layout via the web browser. Browse to a blog post category and place the page in editing mode. A dialog box very similar to Figure 8-24 will appear. Click Edit Page Template so that all related categories reflect your change. Once in edit mode, determine what metadata you can display by using the diagnostic view available in the configuration pane of the SharePoint content search web part. Yes, the content search web part is actually used within the category page to display the catalog content. This allows you to map columns and view the detailed information on the output as shown in Figure 8-24.

To ensure the blog post body HTML is escaped, we have decided to add the publishing page content column to the posts list and use that to enter the content of a post. This in return outputs the HTML correctly when displaying posts via the Content Search web part using Cross-Site Collection Publishing.

Connecting to a Catalog without Integrating Navigation

Now that we have seen how to connect to a catalog with managed metadata navigation, we want to look at how connecting to a catalog without integrated navigation might be different. In our example, the Specter Group communities catalog does not leverage the catalog navigation. We connect to the communities catalog, and then we show the properties and required metadata styled as per the Specter branding in combination with using the Content Search web part and a custom display template.

To get started, first connect to the communities catalog you previously shared on the authoring site by following these steps:

1. On the consuming site, go to Site Settings. Under Site Administration, click Manage Catalog Connections.
2. Click Connect to a Catalog. If the communities catalog was configured properly and crawled by the search indexer, it will appear as shown in Figure 8-25.

   

   Figure 8-25. The communities catalog available on the Specter public web site

3. Click Connect and then under Connection Integration, select the Connect, but do not integrate the catalog option, as shown in Figure 8-26. Using this configuration you are able to use the specific Content Reuse web parts available in the Snippet Gallery.

   

   Figure 8-26. Communities catalog integration options

4. All other options are unavailable at this point, so click OK to complete the connection.

    Note   Because we did not integrate the communities with the Specter Group web site (including catalog item navigation), there will be problems if we simply insert a Content Search web part onto a page. The page will display the catalog contents, but if you hover over any item, you will notice the URL to the item was only partially generated. This is because we must further configure the catalog.

5. Go back to the catalog settings on the consuming site and set the Catalog Item URL Behavior to Make URLs relative to this site as shown in Figure 8-27.

   

   Figure 8-27. Community catalog URL behavior and format configuration

6. Under the Catalog Item URL Format, select the Manually define a URL format option and set the text box value also shown in Figure 8-27. Notice the custom page Community.aspx, as you will need to create that as well. (See the next section, “Creating Landing Pages for a Catalog.”)

Creating a Category Landing Page

Our first step is to create the page that a user will go to when browsing friendly URLs for a catalog, in our case the communities catalog.

We create a page where we will display all of the communities via the search-driven web part. We call this page Communities and add it to the global navigation on our site.

1. Go to Settings Add Page on the top right. When the Add Page modal dialog box appears, type the name Communities.
2. Select the appropriate page layout you wish to use. Review Chapter 7 if you want to create a new page layout.
3. Once the page has been created, edit the page and insert a Content Search web part found under the content rollup category in the Web Part Gallery as shown in Figure 8-28.

   

   Figure 8-28. The Content Search web part is used to display communities from the catalog

Our next step is to configure the Content Search web part to display the communities catalog content. To do this, edit the newly added web part settings.

1. In the Configuration pane, under Search Criteria, click Change Query. A Change modal dialog box will appear.
2. Under Basics, select the Result Source named Specter Authoring Portal - Pages Results, which is the result source automatically created when you connected to this catalog. Once you select this result source, the catalog content is retrieved, as shown in Figure 8-29. In our example, we immediately see two communities in the Search Result Preview pane as these two communities were previously added.

   

   Figure 8-29. Selecting the communities catalog and previewing results

3. The catalog contents are displayed using the standard display template, which is specified in the web part tool pane. You can now configure additional metadata to display by editing the Content Search web part settings as shown in Figure 8-30. To display the community picture, you can include the appropriate managed property.

At this point we can see the communities including the picture and some of the metadata, as shown in Figure 8-31.

Creating a Category-Item Page

When a user clicks on a given category for a category landing page, a category detail page for that specific category should load. For us, when visitors land on the community landing page created in the previous section and they click on a specific community, we want to be able to display further details. To do this, we first create a new publishing page and call it Community as shown on Figure 8-32.

On this page we insert a Content Search web part as we did in the previous section; however, the web part configuration is a bit different. Our objective for this web part is to retrieve the value of the URL QueryString passed to the page so that we can display the specific community details. One of the new features of the Content Search web part allows us to do this by specifying the QueryString name as shown in Figure 8-33 in the web part’s query builder. In addition, we ensure we select the appropriate results on the drop-down menu to only show items from the communities catalog.

Once we have configured the Content Search web part and then click on a given community, the detail page displays additional information or metadata.

Defining a Category-Item Page URL

During our catalog configuration, we specified that the URL behavior was to make URLs relative to the current site. We can easily validate this configuration by hovering over any of the catalog items on the category landing page and verifying the catalog item URL. In our case, if we hover over the Spruce Meadow community, as shown in Figure 8-34, we see the browser status bar displays the URL to this item’s detail page and passes the ListItemID, as previously configured.

Configuring Catalog Navigation for Catalogs without Integrated Navigation

Our last step is to configure the Specter Group web site term labeled “Communities” so that when a user clicks on it via the top navigation, the link goes to a page we specify that displays all of the communities. To do this, go to Site Settings, and click Term Store Managed. With the Term Store Management Tool, expand the site navigation term set, and then click on the term labeled Communities. On the navigation tab, select the Simple Link or Header option. To provide a link to the communities page, you can either browse the web site and pick the page, or simply type it in the textbox as shown in Figure 8-35. Click Save and your top navigation now includes a Community link that points to the communities page.

Creating a Custom List Control Display Template

A list Control display template is used once per search results to wrap the collection of returned items. Each item in turn is displayed using an Item display template, once per item. Our objective is to use the appropriate HTML markup so that the entire collection of items is displayed as per the Specter Group design.

1. To create a new list control, it is best practice to start with an existing display template. You can make a copy of an existing Control display template by navigating to the Master Page Gallery Display Templates Content WebParts folder.
2. Make a copy of the Control_List.html file, and rename it Control_List_Specter.html. The full HTML source code for the out-of-the-box Control_List.html file is shown in Listing 8-1.

   Listing 8-1.  The Full HTML Source Code for the Out-of-the-Box Control_List.html File

   <html xmlns:mso="urn:schemas-microsoft-com:office:office"
           xmlns:msdt="uuid:C2F41010-65B3-11d1-A29F-00AA00C14882">
   <head>
   <title>List</title>
   <!--[if gte mso 9]><xml>
   <mso:CustomDocumentProperties>
   <mso:TemplateHidden msdt:dt="string">0</mso:TemplateHidden>
   <mso:MasterPageDescription msdt:dt="string"><!--a description--></mso:MasterPageDescription>
   <mso:ContentTypeId msdt:dt="string">0x010100203...</mso:ContentTypeId>
   <mso:TargetControlType msdt:dt="string">;#Content Web Parts;#</mso:TargetControlType>
   <mso:HtmlDesignAssociated msdt:dt="string">1</mso:HtmlDesignAssociated>
   </mso:CustomDocumentProperties>
   </xml><![endif]-->
   </head>
   <body>
       <!--
       Warning: Do not try to add HTML to this section.
       Only the contents of the first <div>
       inside the <body> tag will be used while executing
       Display Template code. Any HTML that
       you add to this section will NOT become part of your Display Template.
       -->
       <script>
           $includeLanguageScript(this.url,
               "∼sitecollection/_catalogs/masterpage/Display Templates/Language Files/
               {Locale}/CustomStrings.js");
       </script>
       <!--
           Use the div below to author your Display Template.Here are some things to keep in mind:
           * Surround any JavaScript logic as shown below using a "pound underscore"
            (#_ ... _#) token inside a comment.
           * Use the values assigned to your variables using an "underscore pound equals"
           (_#= ... =#_) token.
       -->
   
       <div id="Control_List">
           <!--#_
           if (!$isNull(ctx.ClientControl) && !$isNull(ctx.ClientControl.shouldRenderControl) &&
                   !ctx.ClientControl.shouldRenderControl()) {
               return "";
           }
           ctx.ListDataJSONGroupsKey = "ResultTables";
           var $noResults = Srch.ContentBySearch.
                 getControlTemplateEncodedNoResultsMessage(ctx.ClientControl);
           var noResultsClassName = "ms-srch-result-noResults";
           var ListRenderRenderWrapper = function(itemRenderResult, inCtx, tpl) {
               var iStr = [];
               iStr.push('<li>'),
               iStr.push(itemRenderResult);
               iStr.push('</li>'),
               return iStr.join(''),
           }
           ctx['ItemRenderWrapper'] = ListRenderRenderWrapper;
           _#-->
           <ul class="cbs-List">
               _#= ctx.RenderGroups(ctx) =#_
           </ul>
           <!--#_
           if (ctx.ClientControl.get_shouldShowNoResultMessage()) {
           _#-->
               <div class="_#= noResultsClassName =#_">_#= $noResults =#_</div>
           <!--#_
           }
           _#-->
       </div>
   </body>
   </html>

    Note   SharePoint will automatically generate and sync the corresponding .js file, which has the same name.

   Looking at the original entire HTML code in Listing 8-1, toward the bottom you will find the <UL> tag used to render the groups as shown in the following snippet. Our task is to change the class name and ID used to match our Specter Design. The out-of-the-box list control HTML code used to wrap items is shown in Listing 8-2.

   Listing 8-2.  Control Template HTML that Wraps and Calls the Item Templates

   <ul class="cbs-List">
       _#= ctx.RenderGroups(ctx) =#_
   </ul>

   Our task is to change the class name and ID used to match our Specter Group design. The out-of-the-box list control HTML code used to wrap items is shown in Listing 8-2.

3. The Specter Group design uses the <UL> tag as well, but we must specify a different class name and we change the HTML to look like Listing 8-3.

   Listing 8-3.  The New Class Name Specified for the HTML Code That Wraps Items

   <ul id="filter-container" class="feature cf">
       _#= ctx.RenderGroups(ctx) =#_
   </ul>

4. One thing we would like to make sure is that when we are specifying this custom control via the Content Search web part tool pane, the appropriate name shows up in the drop-down list that allows for selecting the available list controls. To do this, we simply change the <Title> tag contents at the top of the Control_List_Specter.html file. In our case, we named it Specter Communities List and can be seen in Figure 8-36 as found in the Content Search web part tool pane.

   

   Figure 8-36. The new Specter list control available via the drop-down list in the Content Search web part tool pane

5. At this point, we have finished creating our custom list Control display template so we are ready to save and publish it.

Creating a Custom Item Display Template

We just saw how to create a list Control display template that is used to wrap a list of items returned by a Content Search web part. Creating a custom Item display template that is used once per item returned is not any more difficult. Again, we start by creating a copy of an existing Item display template and then modify this custom template as required.

We start with making a copy of the Item_Large_Picture.html, which can also be found in the Master Page Gallery under the /Display Templates/Content WebParts folder. We make a copy of the existing Display Template and rename it Item_LargePicture.html. Most of the HTML markup provided in the Item display template will stay the same as it is used by SharePoint to configure the file. We only want to change the HTML markup right before the last closing </DIV> tag to render the item as shown in Listing 8-4.

Listing 8-4.  The HTML Markup That Uses the Custom Specter Classes to Render the Item

<span class="_#= specterPropertyType =#_">
   <a href="_#= linkURL =#_" class="thumb" >_#= pictureMarkup =#_
   <div class="date"><div class="d">_#= date =#_</div>
       <div class="m">_#= month =#_</div></div>
   </a>
   <div class="caption">_#= specterPropertyType =#_</div>
</span>

Because our master page includes the appropriate style sheet (refer to Chapter 5 and Chapter 7), our Item display template renders a particular item as expected and is shown in Figure 8-37.