Custom UI Components

Sometimes you want to display more information to your users, than Ucommerce does by default. You may want to display some contextual information from an external source or have a button that calls a custom API. For this purpose, Ucommerce has support for inserting custom web components into specific sections of the UI.

Custom UI Mode

We have made it easy for you as a developer to identify the sections where you can insert your custom components. For this purpose, you can enable Custom UI Mode from Settings, which will display a box with information on how to insert a component in all the places where available. In some places, like the products editor, we also pass in a props object containing relevant context data.

Getting Started

To begin using the Custom UI feature, ensure that using admin account. Navigate to the Settings, and under Developer you'll find the Custom UI mode toggle. Enable this toggle to activate the Custom UI mode.

Activating Custom UI Mode

Once the Custom UI mode is activated, a notification will be displayed in the main navigation area, indicating that you are currently in Custom UI mode. This notification serves as a visual cue to remind you that you're seeing extra sections as potential placeholders for your custom component .

Integrating Custom Components

In Custom UI mode, each page will display placeholders where you can render your custom web components. These placeholders are marked with unique keys, indicating the specific location where your custom component will be displayed.

Viewing Available Properties

Each placeholder includes an anchor labeled 'Show Available Properties.' Clicking on this anchor will reveal an object containing the properties (props) that are passed to your custom component.

Creating Custom Web Components

1. Develop your web component using standard JavaScript.

2. Ensure that your component adheres to the Web Components standard.

Example of web component

class StoresNameLoader extends HTMLElement {
  static get observedAttributes() {
    return ['props'] // Add the props attribute to the list of observed attributes
  }

  constructor() {
    super()
    this.attachShadow({ mode: 'open' })

    this._props = this.getAttribute('props') // Initialize the property from the attribute

    this.container = document.createElement('div')

    this.shadowRoot.appendChild(this.container)

    this.renderElements()
  }

  renderElements() {
    this.container.innerHTML = `
      <h5>Sample of custom web component from Ucommerce</h5>
          <h2>${this._props?.header || ''}</h2>
          <button id="stores-loader-button">Load stores</button>
          <ul id="stores-list"></ul>
  `

    this.shadowRoot
      .getElementById('stores-loader-button')
      .addEventListener('click', () =>
        this.handleClick(this._props.orderGuid, this._props.cultureCode)
      )
  }

  set props(value) {
    // Define a setter for the property
    this._props = value
    this.renderElements()
  }

  get props() {
    // Define a getter for the property
    return this._props
  }

  async handleClick(orderGuid, cultureCode) {
    const path = `stores/shallow?startAt=0&limit=50&cultureCode=${cultureCode}`
    const response = await this._props.ucommerceHttpService(path)

    if (response.status === 200) {
      const ul = this.shadowRoot.querySelector('ul')


      response.data.forEach((store) => {
        const li = document.createElement('li')
        li.textContent = store.name
        ul.appendChild(li)
      })
    }
  }
}

customElements.define('stores-name-loader', StoresNameLoader)

Inserting Components

For setting up your components we recommend creating an extension method on the IUcommerceBuilder encapsulating your configuration and calling it in your program.cs.

public static class MyCustomExtensions
{
    public static IUcommerceBuilder AddMyCustomComponents(this IUcommerceBuilder builder)
    {
        // Add a com    ponent not hosted by the CustomComponentServer
        builder.AddCustomComponentWithUrl(
            "stores-home_main-top", // The key from the Ucommerce backoffice
            "Stores name loader", // The section header
            "stores-name-loader", // The constructor to call in your component
            "https://url.to/your/storesNameLoader.js");

        // Add a component hosted by the CustomComponentServer
        // See Hosting Components in Ucommerce below
        builder.AddCustomComponentWithPath(
            "orders-home_main-bottom", // The key from the Ucommerce backoffice
            "The order top first viewer", // The section header
            "result-component", // The constructor to call in your component
            "webComponentSample.js"); // The path to the file inside the /CustomComponents directory
        return builder;
    }
}

Call your extension method in program.cs when setting up Ucommerce

var ucommerceBuilder = builder.Services.AddUcommerce(builder.Configuration)
    ...
    .AddMyCustomComponents();

Hosting Components in Ucommerce

In order for the backoffice UI to download your custom web component, you will have to host it on a server.

Ucommerce can host your components with the CustomComponentServer.

By default, we look for a directory called /CustomComponents in your web project, so you need to ensure that it exists and is published on your website.

Create the /CustomComponents directory in your project.

Add the following to your Ucommerce project .csproj file to publish the contents of the folder to your Ucommerce website.

</Project>
...
    <ItemGroup>
        <Content Include="CustomComponents\**\*" CopyToPublishDirectory="Always" />
    </ItemGroup>
...
</Project>

Once the directory exists and is published you can enable the CustomComponentServer by calling the UseComponentServer method on the IUcommerceApplicationBuilder application builder.

app.UseUcommerce()
    ...
    .UseCustomComponentServer();