Walkthrough: Creating widget components using the CLI

This walkthrough is the part two of the Rapid development using UI components walkthrough series.

As part of a Sitecore Search implementation, you need to create and add widget components to your React application.

Typically, the configurations in the Customer Engagement Console (CEC) contain the following:

  • A preview search widget, configured to display on all pages.

  • A search results widget, configured to display only on a search results page.

This walkthrough describes how to create a widget component with Search UI components CLI. You need to repeat this walkthrough for every widget in your project.

Alternatively, you can create widget components by manually copying and pasting code from the UI reference site.

This walkthrough describes how to:

  • Install the Search UI Components CLI.

  • Create a widget component with the UI Components CLI.

  • Edit the widget component code to match design.

  • Edit the styles of a styled widget component

  • Style widget components with a theme.

Install the Search UI Components CLI

To install the UI Components CLI:

  1. In the terminal of your IDE, run the following.

    RequestResponsejs
    npx install --save-dev @sitecore-search/cli
  2. In a file called .sc-search-settings.json, add the location where you want to create the widget components as shown in the following code block.

    RequestResponsejs
    {
        "components-path": "src-test/components"
    }

Create a widget component with the Search UI Components CLI.

All results displayed in a widget are of the same type of entity which is a grouping of attributes, populated with metadata extracted from searchable content items. For example, the default content entity has attributes for content type, title, description, and so on.

To create a widget component with Search UI Components CLI:

  1. In the root of your project or in the folder where you have .sc-search-settings.json, run the following in the terminal:

    RequestResponsejs
    npx sc-search new-widget
  2. To create the widget component, provide answers to select a widget template in the displayed prompts. Select a styled template if you want to use theme variables or custom styles.

    You can use theme variables with styled components or apply custom styles.

    Note

    The CLI generates an index.js or index.ts file based on your language choice.

    If you choose a styled template, the CLI also generates a styled.js or styled.ts file.

Edit the widget component model and add attributes to the HTML

When you copy and paste code blocks from the Search UI components reference site, or create widget components using the Search UI Components CLI, the entity or model in the component code might not match an entity in your implementation.

The widget components in the reference site and CLI, are based on the default Content entity. You need to edit and modify the components to match the correct entity or model and attributes.

You cannot use the same widget template for different entities if they have a different set of attributes or model. You need to create a widget component for each entity. The following procedure describes what to modify in the code.

Tip

Include the entity type in the component and file names to identify the entity or model in the code.

To edit the widget component code to use an entity configured in the CEC:

  1. Open the index.js or index.ts file.

  2. In the first section of the file, in the model declaration, if required, replace the name of the model with the entity you want to use.

  3. Match the attributes of the model to those of your entity.

  4. To display values for entity attributes, edit the HTML.

  5. In the widget function, include your entity name.

  6. Save the file.

Caution

You must make sure all attributes used in a widget component have been defined in the CEC and are marked to return in the API.

Invalid entity attributes can throw runtime errors.

Edit the styles of a styled widget component

If the CLI did not generate a styled.js or styled.ts file, skip this procedure.

To edit the styles of a styled widget component to match the design:

  • In the styled.js or styled.ts file, edit the styles.

Style widget components with a theme

Theming an application with CSS variables listed in Search UI components reference is the fastest way to style your components. You can use the default theme or a custom theme.

Do you have some feedback for us?

If you have suggestions for improving this article,