Product DocsMenu

Adding or Customizing a Facet With the .NET Interface Editor

The Coveo .Net Front-End comes with a number of built-in facets that you can easily add to your .NET search interface (see Managing Built-in Facets and Related Results Appearing in a .NET Search Interface).

You can also customize existing facets or create new facets and add them to a .NET search interface.

To add or customize facets with the .NET Interface Editor

  1. Access the Coveo .NET Front-End Interface Editor (see Opening the .NET Interface Editor).

  2. Select the Search Interfaces tab.

  3. On the menu bar:

    1. In the Current Interface drop-down list, select the search interface that you want to modify.

    2. Click the Features menu.

  4. In the navigation panel on the left, click Facets and Related Results.

  5. In the panel on the right:

    • To add a new facet, above the Built-in Facets list, click Add New Facet.

      Note: Creating facets by clicking Add New Facet offers more flexibility than adding built-in facets (however, built-in facets are sufficient most of the time.). (see Managing Built-in Facets and Related Results Appearing in a .NET Search Interface).

      Example: When you create a custom facet using the sysfiletype field, you can leave the Allowed Values parameter box empty and the facet will automatically show facet items for all indexed file types. Otherwise, if you add the Type built-in facet, the facet would restrict facet items to the following values: audio,doc,html,image,mapimail,mime,mpp,msg,one,pdf,ppt,rtf,txt,video,wp,xls,zip.


    • To customize an existing facet, in the Facets and Related Results list, click the facet that you want to modify.

    A page similar to the one shown below appears.

  6. Under Edit Facet, configure the following required parameters:

    1. In the Title box, type the text that you want to see as the caption at the top of the facet. Click the button to also enter the caption translated for all supported languages.

    2. In the Field to Group On drop-down list, select the field whose values are used to build the items listed in the facet.

      Example: Select sysauthor when you want to create a facet that lists the authors of all returned documents.

      Note: When the desired field does not appear in the drop-down list, you need to make the field available using the Administration Tool (see Adding a Facet Field).

  7. Still under Edit Facet, optionally consider changing the default behavior for the following parameters:

    1. In the Field to Display drop-down list, select the field whose values are used to identify the items listed in the facet when different from the Field to Group On parameter.

      Example: You can build a facet based on author IDs with the sysauthorid field but display the corresponding author names with the sysauthor field. The purpose of this procedure is to increase the precision of facet items (because each author ID is unique) without compromising their identification by users (names are more easily recognized than IDs).

    2. If a developer programmed a customized version of the facet code that you want to rather use: 

      1. In the Assembly box, enter the fully qualified assembly name containing the class specified in the Class box.

      2. In the Class box, enter the name of a class (including its namespace) to use to instantiate the facet.

    3. Next to Icon, when you want to use an icon other than the default one next to the facet title:

      1. Click Change.

      2. Click the Choose File button that appears, and then select the icon image file in the dialog box that opens.

      3. Click Upload, to transfer the file from its original location to the Coveo server.

    4. In Zone, select where the facet appears in the search interface:

      • Interface's default facet position: As specified in the in Default Facet Parameter for this search interface.

      • Right: Appears in the vertical zone on the right side of the search interface.

      • Top: Appears in the horizontal zone at the top of the search results. This zone is generally used to host facets or Related Results panels that have a Display Style set to Dropdown.


        1 A Dropdown style facet
        2 The Top zone
      • Left: Appears in the vertical zone on the left side of the search interface.

      Note: You can hierarchically set facet positions for a hub, for a search interface, and for specific facets (see Configuring the Position of Facets and Related Results Panels With the .NET Interface Editor).

    5. In Display Style, select the how the facets appear: 

      • Normal: Default format (see About Facets).

      • Dropdown: The facet appears as a drop-down control that is collapsed by default. This type of facet can only be hosted in the Top zone.

      Example: A Source facet is illustrated below in the two formats.

      Normal Dropdown collapsed Dropdown expanded

      Note: Coveo .NET Front-End 12.0.503+ (December 2013) The facet Dropdown style is reintroduced.

    6. In Display Criteria, select the criteria determining when the facet appears:

      • When there is more than one result: Generally the desired behavior because a facet with one or no value is not useful to refine results.

      • When there is at least one result: Select when you still want to see the facet even if there is only one facet item.

      • Always display: Select when you always want to see the facet, even if it shows no facet item.

    7. If you want to restrict facet items to specific values, in the Allowed Values box, enter a comma separated list of values. Leave the parameter empty to apply no restriction.

      Example: If you wanted to create a Marketing Authors facet listing only authors from your marketing department, enter the list of marketing department employee names. The facet then only shows facet items for these authors.

    8. The Performance parameter selection determines how many returned results are scanned for each query to find the possible facet items. Moving the radio button selection from the left (Faster) to the right (More Precise) increases the number of scanned results.

      Selecting the left-most radio button under Faster (default value) should list all available facet items in a majority of cases since up to the first 1000 returned results are scanned to identify the possible facet items.

      Try selecting a button towards More Precise when you suspect that there is a large number of facet items for this facet and you want to increase the chances that the facet displays all of them.

      Selecting Most Precise ensures that the facet lists all facet items by scanning all query results. Be aware however that the facet display may be very slow with this selection for queries returning a large number of results.

      Example: Let's say an Author facet appears in a search interface for a blog site with thousands of possible authors. When a query returns 80 results, the facet lists all the possible facet items. A second query returns, let's say 5000 results. In this case, because by default the facet only looks at the first 1000 returned results to identify possible authors, it is likely that the facet will not list all authors of the 5000 blog posts.

      Note: The term Precision for this parameter refers to the probability for the facet to list all possible facet items. However, the number of result occurrences appearing between parentheses for each facet item is always accurate.

    9. In the Number of values box, enter the number of facet items that the facet shows by default. When more facet items are available, the More control appears at the bottom of the facet to allow the user to expand the facet to show all facet items. The default value is 5.

      Example: A query returns documents with a large number of different file types.

      With Number of values set to 5, initially only the five most frequent file types are shown.
      With Additional Values Increment set to 10, when you click More, up to ten more file types are shown.
      With Number of Search Values set to 15, when you type characters in the search box, up to 15 matching items can appear in the suggestion list.
    10. In the Additional Values Increment box, enter the number of facet items that are added/hidden each time the user clicks More/Fewer. The default value is 10.

    11. In the Number of Search Values box, enter the maximum number of facet items that appear below the search box, in the list of facet items matching the characters typed in the search box. The default value is 15.

    12. Coveo .NET Front-End 12.0.61+ (December 2012) Select the Enable Facet Search check box to make the search box visible.

      Note: The search box will not appear in the facet when you specify a field in Field to Display above.

    13. In the Dynamic Range Unit drop-down list, when appropriate, select an option to include units to make the range values easier to read:

      • Date: For a facet with date range values, select to show values in the short date format (mm-dd-yyyy) rather than the long date format (mm-dd-yyyy hh:mm:ss) that appears by default.

      • Currency: For a facet with currency range values, select to show the values with decadic multiples of the currency (K for 1000 or M for 1,000,000).

        Example: $500K-$1.499M rather than $500000-$1.499999

      • Bytes: For a facet with file size range values, select to show values in B, KB, MB, GB, or TB units rather than the complete integer values.

        Example: The same File Size facet respectively when No Unit and Bytes is selected in the Dynamic Range Unit drop-down list.

    14. In the Clipping Mode drop-down list, for a facet item whose length exceeds the available width in the facet, select where to truncate the text string and add the ellipsis character.

      Example: While in most cases, it makes more sense to truncate the end of the strings, for a folder facet, it is often more useful to see the end of the path rather than the beginning.

    15. In the Sort Criteria drop-down list, select the criterion controlling the order in which facet items appear:

      • Number of Occurrences: Sorts facet items in descending order according to their number of occurrences in the search results.

        Example: In an Author facet, if John has written 10 documents and Jack 5, then John appears before Jack.

      • Score: Sorts facet items in descending ranking score order. The ranking score gives more points to facet items occurring in documents appearing higher in search results. Consequently, a facet item occurring a few times in top ranking documents appears before a facet item occurring a large number of times in low ranking documents.

        Example: In an Author facet, if John authored only one document but his document is one of the top ranking documents, and Jack authored 200 documents but are ranked low in the search results, then John appears before Jack in the list of facet items.

      • Ascending Alphabetical: Sorts facet items in ascending alphabetical (A to Z) or numerical order.

      • Descending Alphabetical: Sorts facet items in descending alphabetical (Z to A) or numerical order.

      • Correlation: Sorts facet items based on the correlation to the current query using a chi-square method. Items that are particularly related to the query versus the rest of the index appear higher.

        Example: You can use the Correlation option to sort an Expert facet to list people that are particularly related to the queried terms, not just people that are the author of many documents containing the terms.

    16. Besides Depends On, select whether the appearance of this facet is conditional to another facet being used by a user. This feature is useful when the refinement criteria of two facets are linked following a hierarchy.

      Example: When a search interface has both a Year facet and a Month facet, it often makes sense to only show the Month facet after the user has selected a year in the Year facet. To obtain this behavior, for the Month facet, beside Depends On select the Year check box.

    17. Select the Collapse by default check box when you want the facet to initially show only its caption, not facet items.

      This option is useful for example for less frequently used facets when your search interface includes many facets and you want to save vertical space.

  8. Optionally, you can set what icon images appear on the left of each facet item:

    1. For legacy facets only, in Default Image, enter the path and file name for the image to display as the default icon on the left of all facet items. You can specify the full path in the[path]/[image_file] form or the relative path from where the search interface page is stored.

      Example: For an Author legacy facet, enter the path and file name for the  icon using the full path (ex.: or the relative path (ex.: ~/Coveo/Skins/MySearchInterface/icon-author.png).

    2. You can also assign custom icons and captions to specific facet item values: 

      1. Next to Value to Image Mappings, click Add New.

        Three boxes appear where you can specify one or more rules to map icons and captures to facet values.

      2. In the box on the left, type the value of the facet item to which you want to assign a specific icon and/or caption.

      3. In the box in the center, enter the path and file name for the image to display as the icon. You can specify the full path in the[path]/[image_file] form or the relative path from the search interface skin folder in the ~/[Relative_Path]/[Filename] form.

      4. In the box on the right, enter a custom caption for the item value.

      Note: As done for some out-of-the-box facets like the Type facet, you can use an embedded resource (like coveo_embedded_res( or set a callback method (like callback(Coveo.CES.Web.Search.Interfaces.ValueMappingFormatter.GetFileTypeIconUri)) to dynamically get the appropriate facet item icon and caption. Entering a * in the box on the left indicates that these resources or callbacks apply to all items. This feature can be used by the Coveo Professional Services and developers.

      Example: For a document Type facet, you may want to use specific icons and captions for Word and Excel documents and use the standard icons and captions for other file types. You can do that by entering the mappings as follows.

  9. Under Computed Fields, you can optionally configure the facet to calculate and show one or more numerical values for each facet item (see Computed Facets):

    Note: You need a Coveo license that allows computed facets to use this feature.

    1. For each computed value, click Add New next to Computed Fields.

    2. In the Field drop-down box, select the field which values you want to use as the source for the calculation.

    3. In the Operation drop-down box, select the mathematical operation to perform on the field values (Sum, Average, Minimum, or Maximum).

    4. In the Result Display Location drop-down box, select where the calculated value appears in relation with the facet item (Beside the Caption or Under the Caption).

    5. In the Result Prefix and Result Suffix boxes, if needed, respectively type the desired prefix and suffix to appear before and after the calculated values.

      For a multi-lingual search interface, click next to the box to open the dialog box where you can type the translated prefix or suffix for each supported language.

    6. In the Format drop-down box, select the numerical format with which the calculated value appears in the facet (Currency, Integer, Numeric, Percentage, or Custom). When you select Custom, another box appears where you can enter the desired .NET numerical format string.

      Note: Refer to the Standard Numeric Format Strings MSDN documentation for details on the .NET numeric format string.

    7. When you include more than one calculated value, click Up or Down on the corresponding line, to set in which order the calculated values appear.

    8. Click Delete on the corresponding line when you want to eliminate a calculated value.

      Example: You could create a Document Average Size facet in which you see the average file size and the average number of pages for each document type. When it is not possible to calculate a value, like the average number of pages for HTML documents, nothing appears.

  10. Click OK to complete the custom facet creation.

  11. Back in the Facets page, the new facet appears at the end of the Facets and Related Results list where you can:

    1. Click Up or Down to set the position of the facet relative to other facets, for each zone in the search interface.

    2. When you want to eliminate a facet, select a facet and then click Delete.

  12. Using a browser, open or reload the search interface to verify that the facet behaves as you expect.

People who viewed this topic also viewed