THIS IS ARCHIVED DOCUMENTATION

Creating a Hierarchical Facet Component Using the Coveo for Sitecore Legacy Search UI Framework

This is for:

Developer System Administrator

Coveo for Sitecore 4.1 (November 2018)

Coveo for Sitecore comes shipped with a few types of facet by default. These facets are implemented using the standard Facet component coming from the JavaScript Search Framework V1.0 . It turns out that the Framework also has a HierarchicalFacet component. However, Coveo for Sitecore doesn’t implement anything equivalent. The reason is that there’s no field that matches the required value format by default, requiring you to manually create a computed field. This tutorial demonstrates how to create the required classes, files, and items. Specifically, you will learn how to create a category and subcategory hierarchical facet, as shown below:

Requirements

This tutorial assumes that:

  • Your Sitecore instance is installed in C:\inetpub\wwwroot\<SITECORE_INSTANCE_NAME>\.

  • You installed the Coveo for Sitecore 4.0 or newer package and integrated it into one of your Sitecore layouts.

  • You have items with the Category and Subcategory fields of type Single-Line Text.

We recommend that you use project-specific folders for this tutorial. The steps below use Custom as the folder name .

Step 1: Create the Computed Field Class

To display a hierarchical facet, the JavaScript Search Framework needs a field with its data in a specific format. To generate the required data format, a computed field must be created.

  1. Create a new C# project named Coveo.Custom that targets the .Net Framework 4.5.

  2. Add references to the Sitecore.ContentSearch, Coveo.Framework, and Coveo.SearchProviderBase assemblies located in the <SITECORE_INSTANCE_ROOT>\Website\bin folder.

  3. Create a new class named HierarchicalCategoryComputedField that inherits from the ConfigurableComputedField class as in the code sample below.

    using System;
using Coveo.Framework.CNL;
using Coveo.Framework.Items;
using Coveo.SearchProvider.ComputedFields;
using Sitecore.ContentSearch;
​
namespace Coveo.Custom
{
    public class HierarchicalCategoryComputedField : ConfigurableComputedField
    {
        /// <inheritDoc />
        public override object ComputeFieldValue(IIndexable p_Indexable)
        {
            Precondition.NotNull(p_Indexable, () => () => p_Indexable);
​
            IItem item = new ItemWrapper(new IndexableWrapper(p_Indexable));
            string hierarchicalCategory = null;
​
            string categoryFieldValue = item.GetFieldValue("Category");
            if (!String.IsNullOrEmpty(categoryFieldValue)) {
                hierarchicalCategory = categoryFieldValue;
​
                string subcategoryFieldValue = item.GetFieldValue("Subcategory");
                if (!String.IsNullOrEmpty(subcategoryFieldValue)) {
                    hierarchicalCategory += ";" + categoryFieldValue + "|" + subcategoryFieldValue;
                }
            }
​
            return hierarchicalCategory;
        }
    }
}

  4. Compile the project.

  5. Copy the resulting assembly (Coveo.Custom.dll) to the C:\inetpub\wwwroot\Instance\Website\bin folder.

Step 2: Configure the Computed Field

To have a field that contains the hierarchical category with the required format, you must configure it in Coveo for Sitecore.

  1. Using a text editor, open the <SITECORE_INSTANCE_ROOT>\Website\App_config\Include\Coveo.SearchProvider.Custom.config file.

  2. Locate the defaultIndexConfiguration element.

  3. Add a computed field named hierarchicalcategory.

    <defaultIndexConfiguration type="Coveo.Framework.Configuration.CoveoIndexConfiguration, Coveo.Framework">
  <fields hint="raw:AddComputedIndexField">
    <field fieldName="hierarchicalcategory">Coveo.Custom.HierarchicalCategoryComputedField, Coveo.Custom</field>
  </fields>
</defaultIndexConfiguration>

  4. Add the hierarchicalcategory field as a facet and multi-value field in the fieldMap.

    <defaultIndexConfiguration type="Coveo.Framework.Configuration.CoveoIndexConfiguration, Coveo.Framework">
  <fieldMap type="Coveo.Framework.Fields.CoveoFieldMap, Coveo.Framework">
    <fieldNames hint="raw:AddFieldByFieldName">
      <fieldType fieldName="hierarchicalcategory" isFacet="true" isMultiValue="true" settingType="Coveo.Framework.Configuration.FieldConfiguration, Coveo.Framework" />
    </fieldNames>
  </fieldMap>
</defaultIndexConfiguration>

  5. Save and close the file.

Step 3: Re-Index the Items

Sitecore items need to be re-indexed in order to compute the new field and store its value in the Coveo index.

  1. Re-index only the sections of the Sitecore Content Tree that you know contain the items with the Category and Subcategory fields. You can also optionally rebuild your entire search index (see Coveo for Sitecore Indexing Guide).

  2. Validate that the computed field now exists in the Coveo index:

    1. Open the CES Administration Tool.

    2. Access the Index Browser (Content > Index Browser).

    3. In the Coveo index, locate a Sitecore item that contains the Category and Subcategory fields. These fields should be named something like @fcategory12345 and @fsubcategory12345 (see Finding Documents Using the Index Browser).

    4. Examine the other fields of this item by expanding the Details > Fields tab.

    5. Validate that the hierarchicalcategory field now exists.

Step 4: Create the Layout and View Files

To display a hierarchical facet, the JavaScript Search Framework needs a div element with CoveoHierarchicalFacet as the value of its class attribute. In Coveo for Sitecore, facet components are implemented using a layout (Web Forms) or a view (MVC) file. You must also create such files when you implement a hierarchical facet.

Web Forms

  1. Access your Sitecore instance layouts folder (<SITECORE_INSTANCE_ROOT>\Website\layouts).

  2. Create a subfolder named Custom.

  3. Copy the <SITECORE_INSTANCE_ROOT>\Website\layouts\Coveo\CoveoFacet.ascx sublayout file to the Custom layouts folder.

  4. Rename it to CustomCoveoHierarchicalFacet.ascx.

  5. Open it in a text editor.

  6. Change the value of the class attribute from CoveoFacet to CoveoHierarchicalFacet as in the code sample below.

    <div class="CoveoHierarchicalFacet" data-title='<%= Model.Title %>' ...></div>

  7. Save and close the file.

MVC

  1. Access your Sitecore instance views folder (<SITECORE_INSTANCE_ROOT>\Website\Views).

  2. Create a subfolder named Custom.

  3. Copy the <SITECORE_INSTANCE_ROOT>\Website\Views\Coveo\Web.config file to the Custom views folder.

  4. Copy the <SITECORE_INSTANCE_ROOT>\Website\Views\Coveo\FacetView.cshtml view file to the Custom views folder.

  5. Rename the copied file to CustomHierarchicalFacetView.cshtml.

  6. Open the file in a text editor.

  7. Change the value of the class attribute from CoveoFacet to CoveoHierarchicalFacet as in the code sample below.

    <div class="CoveoHierarchicalFacet" data-title='@Model.Title' ...></div>

  8. Save and close the file.

Step 5: Create the Sublayout and Rendering Items

To be able to add and configure hierarchical facets in a search page layout details, a sublayout (Web Forms) and a rendering (MVC) must be created.

  1. Log into the Sitecore Desktop.

  2. Open the Content Editor (Sitecore Start Menu > Content Editor).

  3. For Web Forms:

    1. In the left-hand side panel (Content Tree), select the /sitecore/Layout/Sublayouts item.

    2. Create a sublayout folder named Custom.

    3. Copy the /sitecore/Layout/Sublayouts/Coveo/Coveo Facet sublayout to the Custom sublayout folder (Right-click > Copying > Copy To).

    4. Rename the copied sublayout to Custom Coveo Hierarchical Facet.

    5. Select the /sitecore/Layout/Sublayouts/Custom/Custom Coveo Hierarchical Facet sublayout.

    6. In the right-hand side panel, select the Content tab.

    7. Change the value of the layout Ascx file field to /layouts/Custom/CustomCoveoHierarchicalFacet.ascx.

    8. Save the sublayout.

  4. For MVC:

    1. In the left-hand side panel (Content Tree), select the /sitecore/Layout/Renderings item.

    2. Create a rendering folder named Custom.

    3. Copy the /sitecore/Layout/Renderings/Coveo/Coveo Facet View rendering to the Custom rendering folder (Right click > Copying > Copy To).

    4. Rename the copied rendering to Custom Coveo Hierarchical Facet View.

    5. Select the /sitecore/Layout/Renderings/Custom/Custom Coveo Hierarchical Facet View rendering.

    6. In the right-hand side panel, select the Content tab.

    7. Change the value of the view Path field to /Views/Custom/CustomHierarchicalFacetView.cshtml.

    8. Save the rendering.

Step 6: Create the Facet Item

To be able to select the hierarchicalcategory field in the hierarchical facet sublayout and rendering properties editor, a facet item must be created.

  1. In the left-hand side panel (Content Tree), expand the /sitecore/System/Settings/Buckets/Facets item.

  2. Duplicate the /sitecore/System/Settings/Buckets/Facets/Author item (Right-click > Duplicate) and name it Hierarchical Category.

  3. In the right-hand side panel, select the Content tab.

  4. Change the item name (Facet > Name) to Hierarchical Category.

  5. Change the item field name (Facet > Field Name) to hierarchicalcategory.

  6. Save the item.

Step 7: Add the Hierarchical Facet to the Search Page

Facets can be added to a Coveo-powered search page from the Page Editor or the Layout Details dialog. In the Page Editor, the coveo-facets placeholder is configured in such a way that it only suggests a predetermined set of facets to add (that is, those that come shipped with Coveo for Sitecore). For this reason, hierarchical facets can only be added to a Coveo-powered search page from the Layout Details dialog. However, once added, they can be configured and re-ordered from the Page Editor.

  1. In the left-hand side panel (Content Tree), select the Coveo-Powered Search Page item in which you want to add the hierarchical facet.

  2. Open the Layout Details dialog of this item (Presentation > Details).

  3. For the Default device, select Edit under the list of controls.

  4. In the Device Editor dialog, under Controls, click Add.

  5. In the Select a Rendering dialog, select the appropriate rendering and placeholder.

    1. Web Forms

      1. Rendering: /Sublayouts/Custom/Custom Coveo Hierarchical Facet

      2. Placeholder name: /coveo-search/coveo-facets

    2. MVC

      1. Rendering: /Sublayouts/Custom/Custom Coveo Hierarchical Facet View

      2. Placeholder name: /coveo-search-mvc/coveo-facets-mvc

  6. Ensure that the Open the Properties dialog box immediately checkbox is checked.

  7. Click Select.

  8. In the properties dialog box:

    1. Set the title (Basic Settings > Title) to Category.

    2. Set the field (Basic Settings > Field) to Hierarchical Category.

    3. Change the number of values ( Basic Settings > Number of Values ) to 10000 to ensure that all the categories are listed by the facet.

    4. Click OK to close the properties dialog box.

  9. Click OK to close the Device Editor dialog.

  10. Click OK to close the Layout Details dialog.

  11. Validate the result by opening the Coveo-Powered Search Page in Preview mode (Publish > Preview) or Edit mode (Publish > Page Editor).