Product DocsMenu

Configuring Query Completions in .NET Search Boxes

In a Coveo .NET Front-End search interface, you can configure and activate the query completion feature by adding code to the CoveoSearch.ascx file associated with a skin. The query completion configuration applies to all Coveo search boxes appearing in .NET search interfaces using the skin.

You can configure the query completion to use one or more of the following providers.

FileCompletionProvider

Query completion suggestions are taken from a flat completion text file stored in the skin folder. The completion file must contain one suggestion per line. A suggestion may contain many words. Ensure to save the file using the UTF8 encoding to ensure that special characters such as accented ones are rendered correctly.

The default file name is completions.txt, but you can use a different file name using the FileName attribute.

Order in which suggestions appear below the Search box:

  1. Suggestions where the entered query matches the beginning of the first term in the suggestion sorted alphanumerically.

  2. Suggestions where the entered query matches the beginning of other terms in the suggestion sorted alphanumerically.

Tip: In a document repository, useful query completion suggestions are the titles of documents available in the repository. For repositories with relatively static content and no restriction to who can see titles for all documents, you can easily create a file containing the list of titles for all documents in a repository. In a .NET search interface for this repository, run the @uri query to return all documents. Export the search results to an Excel file (see Exporting Search Results to Microsoft Excel in a .NET Search Interface). Copy the Title column content to the completions.txt file.

FieldCompletionProvider

Query completions suggestions are taken from the list of available fields when the user types @ optionally followed by other letters to refine the list of suggestions.

Once a string type facet enabled field is selected followed by the equal symbol, query completion suggestions are taken from matching field values (see Adding a Facet Field).

You can define aliases so that the user does not need to enter the @sys part of the field name.

You can also specify a default field (for string type facet enabled fields only), so that the user does not have to enter the field name at all. The suggestions are taken directly from the default field values.

Order in which suggestions appear below the search box:

  1. Suggestions where the entered query matches the beginning of the first term in the suggestion sorted by:

    1. Decreasing number of occurrences

    2. Alphanumerical order

  2. Suggestions where the entered query matches the query anywhere in the suggestion again sorted by:

    1. Decreasing number of occurrences.

    2. Alphanumerical order

Examples: When the user types the beginning of a field name like @sysl, the suggestions match available field names.

The user can then select a string type facet field like @syslanguage, add an equal symbol (=), and start adding characters to get suggestions for matching field values.

With the field alias definition <ces:FieldAlias Alias="Concept" Field="@sysconcepts" />, the user can type Concept: in the search box and start adding characters to get suggestions for matching field values.

With the @sysconcepts field set as the default field, the suggestions directly match document concepts.

EmailCompletionProvider

Query completion suggestions are taken from sender/recipient email fields (to, from, cc, bcc).

The user gets suggestions for a specific field by typing a field alias followed by a colon character, and then typing the first characters of the name.

Order in which suggestions appear below the search box:

  1. Suggestions where the entered query matches the beginning of the first term in the suggestion sorted by:

    1. Decreasing number of occurrences

    2. Alphanumerical order

  2. Suggestions where the entered query matches the query anywhere in the suggestion again sorted by:

    1. Decreasing number of occurrences.

    2. Alphanumerical order

Note: The EmailCompletionProvider is activated by default in the out-of-the-box My Emails .NET search interface.

AnalyticsCompletionProvider

Query completion suggestions are taken from queries in the search history of the Usage Analytics Module.

You can configure the scope of the suggestions to be for past queries:

  • Entered by all users versus only the current user (using the LimitToCurrentUser attribute).

  • Entered in any .NET search interface versus only in the current search interface (using the LimitToCurrentInterface attribute).

No suggestions are presented when the Usage Analytics Module is not active (see Deploying the On-Premises Usage Analytics Module).

Suggestions where the entered query matches the beginning of the first term in the suggestion are sorted by:

  1. Decreasing number of occurrences.

  2. Alphanumerical order.

Note: The AnalyticsCompletionProvider is activated by default in all the out-of-the-box .NET search interfaces except My Emails.

MetaCompletionProvider

Query completion suggestions are mixed from two or more completion providers.

You can use providers of the same or of different types but mixing disparate suggestion types may be confusing for the end-user.

The order in which suggestions appear below the search box depends on the type of completion providers that are used.

To configure and activate query completions in a .NET search interface

  1. On the Coveo Master server, open the folder corresponding to the skin used by the .NET search interface for which you want to enable the query completions ([.Net_Front-End_Path]\Web\Coveo\Skins\[Search_Interface_Skin]).

    You can find the skin used by a .NET search interface from the .NET Interface Editor (Search Interfaces tab > Features menu > General page).

    Example: The folder for the skin used by the My Email .NET search interface is typically in C:\Program Files\Coveo .NET Front-End 12\Web\Coveo\Skins\Email.

  2. Using a text editor:

    1. Open the CoveoSearch.ascx file found in the skin folder.

    2. After the ASP.NET directives and before the user control HTML markup, add one of the following completion provider element:

      Example: The following code sample shows the default CoveoSearch.ascx file for the Default skin. Notice the location of the <ces:FieldCompletionProvider...> element .
      <%@ Control Language="c#" AutoEventWireup="false" Inherits="Coveo.CES.Web.Search.Controls.SearchControl" %>
      <%--**************************************************************************
      * This user control defines the look and structure of the CES search interface.
      **************************************************************************--%>
      
      <ces:FieldCompletionProvider id="fcp" BindTo="Interface" DefaultField="@systitle" runat="server" />
      
      <div class="CesSearch">
        <ces:SearchUpdatePanel id="mup" BlankOnHistory="true" runat="server">
          <ces:LoadIfActive Path="TopMenu.ascx" WithID="t" runat="server"/>
          <ces:LoadIfActive Path="InitialPanel.ascx" WithID="i" runat="server"/>
          <ces:LoadIfActive Path="SearchPanel.ascx" WithID="s" runat="server"/>
          <ces:MainUpdatePanel runat="server">
            <ces:LoadIfActive Path="ResultsPanel.ascx" WithID="rs" runat="server"/>
            <ces:LoadIfActive Path="LoginPanel.ascx" WithID="l" runat="server"/>
            <ces:OpenSearchProvider runat="server"/>
            <ces:SearchBar runat="server"/>
            <ces:DebugInfo runat="server"/>
          </ces:MainUpdatePanel>
        </ces:SearchUpdatePanel>
      </div>
      • FileCompletionProvider element:

        <ces:FileCompletionProvider id="fcp" BindTo="Interface" runat="server" FileName="[MyCompletionFile].txt" />                               

        where you replace [MyCompletionFile] by the name of your custom text file, or simply omit the FileName optional attribute to use the completions.txt default file name.

        Important: The text file containing the completions must be stored in the same skin folder.

      • FieldCompletionProvider element:

        <ces:FieldCompletionProvider id="fcp" BindTo="Interface" DefaultField="@systitle" runat="server" />
          

        where the optional FieldCompletionProvider attribute is:

        DefaultField

        Specifies the CES field to use by default for the source of completions when no other field or alias is explicitly specified by the user.

        You can also include optional aliases as follows:

        <ces:FieldCompletionProvider id="fcp" BindTo="Interface" DefaultField="@systitle" runat="server">
          <Aliases>
            <ces:FieldAlias Alias="Author" Field="@sysauthor" />
            <ces:FieldAlias Alias="Type" Field="@sysfiletype" />
          </Aliases>
        </ces:FieldCompletionProvider>  

        where the optional FieldAlias attributes are:

        UseAlias

        Set this attribute to True so that after selecting a suggestion, the alias appears in the search box rather than the corresponding field name (ex.: Concept not @sysconcept). A CES alias with the same name must exist for the same field (see Available Field Aliases). Omit or leave this attribute to False, the default value, when no CES alias is defined to prevent the occurrence of errors.

        IsPreloaded

        Set this attribute to True to load the field values in cache memory when the search session starts to prevent having to wait for the suggestion list to appear. Be aware that a field with a large number of values can take a significant amount of cache memory. The default value is False.

      • EmailCompletionProvider element:

        <ces:EmailCompletionProvider id="emcp" BindTo="Interface" runat="server" />                               
      • AnalyticsCompletionProvider element: 

        <ces:AnalyticsCompletionProvider id="ancp" BindTo="Interface" runat="server" LimitToCurrentUser="True" LimitToCurrentInterface="True" CompletionTimeout=2 />                               

        where the optional EmailCompletionProvider attributes are:

        LimitToCurrentUser

        Set by default to True to limit the completion scope to past queries entered by the current user. Set to False to expand the completion scope to past queries entered by all users.

        LimitToCurrentInterface

        Set by default to True to limit the completion scope to past queries entered in the current .NET search interface. Set to False to expand the completion scope to past queries entered in any .NET search interface.

        LookForPrefixInsideQueries

        Set by default to False to only return suggestions matching the first term of the suggestions. Set to True to return suggestions matching the beginning of terms anywhere in the suggestions.

        CompletionTimeout

        Set by default to 30 seconds, the maximum time the query completions function waits for suggestions from the Usage Analytics Module.

      • MetaCompletionProvider element:

        Example: To use two different FileCompletionProvider files:
        <ces:MetaCompletionProvider id="mcp" BindTo="Interface" runat="server">
          <ces:FileCompletionProvider id="fcp1" FileName="ACompletionFile.txt" runat="server" />
          <ces:FileCompletionProvider id="fcp2" FileName="AnotherCompletionFile.txt" runat="server" />
        </ces:MetaCompletionProvider>                  

        where the optional MetaCompletionProvider attribute is:

        CompleteWithNext

        Set by default to False to stop calling sub-completion providers as soon as one provider returns at least one completion. Set it to True to force the meta completion provider to continue to get completions until it reaches the maximum number of results defined by the MaxCompletions attribute.

        Note: The completion providers declared inside a MetaCompletionProvider element should not include a BindTo attribute. These attributes are ignored if present.

    3. For all completion providers, you can use the following optional attributes:

      Note: You can omit optional attributes to automatically use the default value.

      MaxCompletions

      Determines the maximum number of suggestions to display below the search box. The default value is 10.

      CompletionMaxLength

      Determines the maximum number of suggestion characters to show. When the length of a suggestion exceeds the maximum value, the end of the suggestion text is truncated and replaced by an ellipse ("..."). When a truncated suggestion is selected, a tooltip appears to show the complete suggestion text. This parameter is useful to prevent line wrapping for long suggestions. The default value is 45.

      Example: Customizing the maximum number of suggestions and the maximum number of characters in a suggestion.
      <ces:FileCompletionProvider id="fcp" BindTo="Interface" runat="server" MaxCompletions="20" CompletionMaxLength="30" />

      QueryFormat

      Allows to customize the query sent to CES based on the text entered by the user using the %Value% token.

      Example: You configured the FileCompletionProvider with a file that contains author names but you want to automatically create a @author field query with the selected suggestion. To do so, you can configure the completion provider as follows:
      <ces:FileCompletionProvider id="fcp" BindTo="Interface" QueryFormat='@sysauthor="%VALUE%"' runat="server" />  

      When the selected suggested value is John Smith, the resulting query that appears in the search box is @sysauthor="John Smith" rather than just John Smith, ensuring that only documents with this field value are returned, not any documents containing John Smith.

      It is recommended to enclose the replacement value with quote marks to prevent breaking suggestions containing spaces, and consequently enclose the QueryFormat value with single quotes as follows:

      Example: QueryFormat='@author="%VALUE%"'

      Note: You can also bind a completion provider to a hub (BindTo="Hub") so that search boxes in all .NET search interfaces in the hub inherit the completion provider. A completion provider BindTo="Interface" declaration in a skin overwrites the hub bound completion provider for search boxes in a .NET search interfaces using this skin.  You can also bind a completion provider to a specific control, which overwrites a skin bound completion provider.

    4. The suggestion matching characters are highlighted in bold by default in the suggestion list but you can customize the highlighting appearance by adding to the CoveoSearch.ascx file the CSS classes shown in the following example, and adapt the CSS code as you wish.

      Example: With the CSS classes:
      <style type="text/css">
        .CnlAutoCompleteDropdownItem span
        {
          color: red;
        }
      
        .CnlAutoCompleteDropdownItemSelected span
        {
          color: blue;
        }
      </style>  

      When the user types jo, the span section in the <span>Jo</span>hn Smith suggestion appears in red in the list and in blue when the mouse is over the suggestion.

    5. Save the changes to the file.

    Note: By default, the provider waits for 250 mS after a user starts typing to get and propose suggestions. The provider does not wait for a minimum number of characters. You can change the delay by adding the attribute TypingDelay="500" in the <ces:query/> control in the skins (InitialPanel and SearchPanel). The provider waits for that number of milliseconds after the last keystroke to fire the AJAX call to get the completions.

  3. Clear the cache of your browser and reload the .NET search interface page to validate that the query completion suggestions are available in the search box.

People who viewed this topic also viewed