Ucommerce
  • Ucommerce Next Gen
    • Getting Started
      • Prerequisites
      • Licensing
      • Ucommerce Templates
      • Headless Template
      • MVC Template
    • Headless
      • Postman Collection
      • Headless API Authentication
        • Token endpoint - Authorization Header
        • Authorization Scopes
        • Refreshing the Access Token
      • Reference
        • Cart
        • Cart / Order Line Items
        • Shipment
        • Billing
        • Promotion Codes
        • Price Groups
        • Payment Methods
        • Countries
        • Shipping Methods
        • Catalogs
        • Cart Custom Properties
        • Line Item Custom Properties
        • Orders
        • Views for Cart modifying operations
      • Custom Headless APIs
      • Error Handling
      • Pagination
      • Deprecation
    • Backoffice Authentication
      • Microsoft Entra ID Example
      • Auth0 Authentication Example
    • Definitions
      • What is a Definition
    • Search and indexing
      • Configuration
      • Indexing
        • Index Definitions
        • Facets
        • Indexing Prices
        • Suggestions
        • Custom Data
      • Searching
    • Payment Providers
      • Stripe Provider Integration
      • Implementing a custom payment provider
    • Data Import
    • Miscellaneous
      • Media
      • Price Group Inheritance
      • Price Group Criteria
      • Soft Deletion Of Entities
      • Logging
      • OpenTelemetry
    • Extensions
      • Extending Pipelines
        • Order Processing Pipelines
        • Checkout Pipelines
      • Changing Service Behavior
        • Images
        • Content
      • Custom Headless APIs
      • Extend the Backoffice
        • Custom UI Components
      • Custom Editor UI
      • Custom Promotion Criteria
      • Custom Price Group Criteria
    • How-To
      • Migrate from Classic
        • Common database issues
      • Entities from code
        • Bootstrapping data on startup
        • Product Definitions & Fields
      • Discover pipelines and their tasks
      • Executing a pipeline
    • Integrations
      • Umbraco Media Delivery API
      • App Slices
        • Product Picker
  • Release Notes
  • Contact Us
Powered by GitBook
On this page
  • Custom UI Mode
  • Getting Started
  • Creating Custom Web Components
  • Inserting Components
  • Hosting Components in Ucommerce

Was this helpful?

  1. Ucommerce Next Gen
  2. Extensions
  3. Extend the Backoffice

Custom UI Components

PreviousExtend the BackofficeNextCustom Editor UI

Last updated 1 year ago

Was this helpful?

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 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();

web components