THIS IS ARCHIVED DOCUMENTATION

Deploy Coveo for Sitecore JSS

This is for:

Developer System Administrator
Warning

Coveo will be sunsetting Coveo for Sitecore JSS in March 2023. Coveo for Sitecore JSS documentation will no longer be available after this date.

We recommend Coveo for Sitecore JSS users migrate their search interfaces. The Coveo Atomic and Headless libraries let you use your preferred web application framework (for example, React, Angular, Vue.js) to build search interfaces.

You’ve installed Coveo for Sitecore JSS. You’re now ready to add Coveo for Sitecore components to your Sitecore JSS app and to deploy your app.

Adding Coveo Components to Your JSS App Route YML Files

A typical search solution implementation consists of a full-fledged Coveo-powered search page and content pages with a Coveo global search box in their header section, with searches performed in the global search box being redirected to the main search page.

Adding the Main Search Page

  1. In your JSS app, under the data/routes folder, create a folder called search.

  2. In your data/routes/search folder, create an en.yml file.

  3. Follow the instructions associated with your search page implementation strategy (see Leading Practices). Select Using the Coveo Hosted Search Page component (recommended) or Adding a search page as a collection of single-purpose components.

    • Using the Coveo Hosted Search Page component (recommended)

      1. If you haven’t already done so, create a very basic classic hosted search page in your Coveo organization. Note its name as you’ll need it later.

        Note

        Don’t spend time creating an elaborate classic hosted search page at this stage. Team collaboration to improve your search page iteratively is the subject of the Create Hosted Search Pages article, later in the workflow.

      2. Copy and paste the contents of the following code block in your data/routes/search/en.yml file.

        Initial data/routes/search/en.yml file content
        fields:
  pageTitle: Hosted Search Page
placeholders:
  jss-main:
    - componentName: CoveoSearchbox
      fields:
        cssClass:
        id:
        hiveDataSource: ''
    - componentName: CoveoHostedSearchPage
      fields:
        cssClass:
        id:
        hiveDataSource: ''
    - componentName: CoveoSearchResources
      fields:
        cssClass:
        id:
        hiveDataSource: ''

      3. Save your changes.

      4. Proceed to Adding a Header Global Search Box to a JSS App Route.

    • Adding a search page as a collection of single-purpose components.

      You’ll need to add your single-purpose components to your data/routes/search/en.yml file and link each component in the .yml file to a data source using the hiveDataSource field. For further instructions, see Adding and Configuring Coveo for Sitecore JSS Components.

Adding a Header Global Search Box to a JSS App Route

The following instructions use the Home route of your JSS app as an example.

  1. In a text editor, open the data/routes/en.yml file of your app.

  2. Copy and paste the contents of the code block below in your data/routes/en.yml file.

    Initial data/routes/en.yml file content
    fields:
  pageTitle: Coveo for Sitecore | Sitecore JSS
placeholders:
  jss-main:
    - componentName: CoveoSearchbox
      fields:
        cssClass:
        id:
        hiveDataSource: ''
    - componentName: CoveoSearchResources
      fields:
        cssClass:
        id:
        hiveDataSource: ''

  3. Save your changes.

Feeding Data to Your Components

Note

Instructions in this section apply when the Coveo Hosted Search Page component is used. If you’re building your main search by assembling single-purpose components, see Adding and Configuring Coveo for Sitecore JSS Components for general instructions.

Coveo components receive data from Coveo Hive data sources, which are referenced by the hiveDataSource field located in the .yml file. You will first need to create the necessary Coveo for Sitecore data source branch.

To create the data source branch

  1. In the Sitecore Content Editor, right-click the Home item and select Insert > Insert from template.

  2. Under Templates > Branches > Coveo Hive, select Coveo Global Parameters Folder.

  3. For the sake of simplicity, name the item DataSourcesForJSS.

Feeding Data to Your Main Search Page Components

  1. Under the DataSourcesForJSS item in the content tree, right-click the Global Search Pages item and select Insert > Hosted Search Page.

  2. Name the new item Hosted Search Page. This is the data source for the CoveoHostedSearchPage component your JSS app home/search route will use.

  3. In the data source you just created, use the Search Page field dropdown menu to select the Coveo organization hosted search page you created in the Adding the Main Search Page section.

  4. In the data source you just created, provide a value for the Search Hub field.

    Hosted Search Page component data source configuration | Coveo for Sitecore 5
    Important

    Many powerful Coveo features (for example, analytics reporting and machine learning driven features) rely on search hub values. Meaningful search hub values are also essential in identifying the origin of all calls to the Coveo Search API, as this can avoid you accidental extra costs.

    Regardless of the way you build your search interfaces (or the other methods you may use to call the Search API), ensure you set search hub values properly from the beginning.

  5. Save your changes to the item.

  6. In the data/routes/search/en.yml file, set the value of the CoveoHostedSearchPage component hiveDataSource field value to the Item ID of the Hosted Search Page data source item.

    Example of data/routes/search/en.yml file at this point
    fields:
  pageTitle: Hosted Search Page
placeholders:
  jss-main:
    - componentName: CoveoSearchbox
      fields:
        cssClass:
        id:
        hiveDataSource: ''
    - componentName: CoveoHostedSearchPage
      fields:
        cssClass:
        id:
        hiveDataSource: '1CED416F-330F-4546-8067-3152BB16A453'
    - componentName: CoveoSearchResources
      fields:
        cssClass:
        id:
        hiveDataSource: ''

  7. Under the DataSourcesForJSS item in the content tree, right-click the Global Search Boxes item and select Insert > Coveo Global Searchbox.

  8. Name the new item Coveo Global Searchbox and click OK. This is the data source for the CoveoSearchbox component your JSS app home/search and home routes will both use.

  9. In the data source you just created, use the Search Page URI field droptree to select your JSS app main search page route (that is, home/search).

    Global Searchbox component data source configuration | Coveo for Sitecore 5

  10. Save your changes to the item.

    Important

    When you delete your JSS app item in the Sitecore Content Editor, the Search page URI field in the Coveo Global Searchbox data source is automatically emptied. If you need to redeploy your JSS app at any time, don’t forget to go back into the Coveo Global Searchbox data source and set the Search page URI field.

  11. In the data/routes/search/en.yml file, set the value of the CoveoSearchbox component hiveDataSource field value to the Item ID of the Coveo Global Searchbox data source item.

  12. Repeat the steps you performed for the CoveoHostedSearchPage and CoveoSearchbox components but, this time, to create and link a data source for the CoveoSearchResources component your home/search and home routes will use. The Coveo Search Resources data source template is located in the Global Resources folder of the data source branch. You don’t need to set any field values in the Coveo Search Resources data source.

    Example of data/routes/search/en.yml file once populated
    fields:
  pageTitle: Hosted Search Page
placeholders:
  jss-main:
    - componentName: CoveoSearchbox
      fields:
        cssClass:
        id:
        hiveDataSource: '669466ED-4272-4C2F-823C-A486F25D0036'
    - componentName: CoveoHostedSearchPage
      fields:
        cssClass:
        id:
        hiveDataSource: '1CED416F-330F-4546-8067-3152BB16A453'
    - componentName: CoveoSearchResources
      fields:
        cssClass:
        id:
        hiveDataSource: 'ED76DA0B-72D7-49F4-9154-85680CD7D37C'

Feeding Data to Your Header Global Search Box Components

The home app route item contains a Coveo Global Searchbox and a Coveo Search Resources component. You can reuse the data sources you created in the main search page for these two components. To do so, copy the hiveDataSource values you entered for the CoveoSearchbox and CoveoSearchResources components in the data/routes/search/en.yml file and paste them in the corresponding hiveDataSource fields in the data/routes/en.yml file.

Example of data/routes/en.yml file once populated
fields:
  pageTitle: Coveo for Sitecore | Sitecore JSS
placeholders:
  jss-main:
    - componentName: CoveoSearchbox
      fields:
        cssClass:
        id:
        hiveDataSource: '669466ED-4272-4C2F-823C-A486F25D0036'
    - componentName: CoveoSearchResources
      fields:
        cssClass:
        id:
        hiveDataSource: 'ED76DA0B-72D7-49F4-9154-85680CD7D37C'

Deploying Your JSS App to Your Sitecore Instance

When Coveo for Sitecore JSS components have been added and configured in your Sitecore JSS app, you’re ready to deploy your app.

  1. In a terminal, with your app folder being the active folder, run: jss deploy config, and then jss deploy app -c -d to deploy your app to your Sitecore instance.

  2. Browse the home app route item created under your Sitecore instance parent app item. This home item will contain a global search box.

  3. Type a search keyword in the global search box and then select Enter. This redirects the query to your search page.

    Note

    If the home item query redirects to a URL on another host name, you need to update the <site> element hostName attribute value in the <APP_NAME>\sitecore\config\<APP_NAME>.config file.

    If you notice CSS-related styling issues in your search item, this could be because your Coveo organization hosted search page is not using the same version of the Coveo JavaScript Search Framework as your Coveo Search Resources component. If need be, update your Coveo organization hosted search page Search UI version.

    Hosted Search Page UI version | Coveo for Sitecore 5

    Coveo for Sitecore release notes pages, accessible through the Releases and Downloads page, indicate the version of the Coveo JavaScript Search Framework that is included with your version of Coveo for Sitecore (that is, 2.10083 in the following example).

    Finding the JavaScript Search Framework version included in your version of Coveo for Sitecore | Coveo for Sitecore 5

ClickableUri Values in Headless Server-Side Rendering Mode

When setting up a proxy to the Sitecore server, you need to configure Sitecore to ensure your search page result ClickableUri values reflect the proxy host name rather than your Sitecore server host name. To achieve this, patch the relevant Sitecore <site> configuration element(s) to target your proxy.

Example

You have items to index on your Sitecore server whose URL is http://sc920.sc. You need your Coveo-powered search page results to have ClickableUri values that target your proxy whose URL is http://mysite.com.

  1. Create a patch file called ProxyUri.config in the <SITECORE_INSTANCE_ROOT>\App_Config\Include\Coveo folder.

  2. Open ProxyUri.config in a text editor.

  3. Copy and paste the following content in the ProxyUri.config file.

    <configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
    <sites>
      <!--We assume below that all items are associated with the default Sitecore "website" site. If required,
          adjust the <site> element "name" attribute value. Apply a patch like the one below for all appropriate
          <site> elements.-->
      <site name="website" >
        <patch:attribute name="hostName">sc920.sc.*</patch:attribute>
        <patch:attribute name="targetHostName">mysite.com</patch:attribute>
      </site>
    </sites>
  </sitecore>
</configuration>

  4. Save your changes.

  5. Publish your site.

  6. Rebuild your indexes.

What’s Next?

You may now want to improve your main search page.