Configure Open UI Pickers from Scratch

Info: This feature requires a standard or premium Bloomreach Content license. Contact Bloomreach for licensing details.

Overview

This guide describes how to configure Commerce Open UI Pickers in non-Bloomreach Commerce Accelerator projects using brXM version 14 or 15.

If you are working with Bloomreach Commerce Accelerator v14, refer to Configure Open UI Pickers in Bloomreach Commerce Accelerator.

Starting with version 14.6.1, you can use Commerce Open UI Pickers in non-Accelerator projects to associate documents with commerce categories, products, and accounts. The pickers interact with the optional brX GraphQL Service using its GraphQL API.

When to Use

Use this configuration to enable editors to select commerce categories, products, or product variants in any document type, integrating commerce data with your content.

Prerequisites

  • brXM v14.6.1 or later
  • Access to the brX GraphQL Service
  • Project permissions to update dependencies and JCR configuration

Field Mapping Example

For demonstration purposes, this guide assumes that your document types use the following fields in the myproject: namespace to store commerce connector and product IDs:

Commerce Open UI PickerExtra Fields
Category Pickermyproject:connectorid for Connector ID
Product Pickermyproject:connectorid for Connector ID
Product Variant Pickermyproject:connectorid for Connector ID, myproject:productid for Product ID

You can use different field names and namespaces as needed. If you do, update the field references in the configuration steps below.

Each picker retrieves data from the brX GraphQL Service. You must specify the GraphQL service URL in each picker configuration.

Add the Commerce Open UI Pickers Dependency

Add the Commerce Open UI Pickers module to your project.

  1. In your root pom.xml, define the starterstore.version property. Use a version in the 14.7.X range, even for brXM v15 projects.

      <properties>
    <!-- ... -->
    <starterstore.version>14.7.X</starterstore.version>
    <!-- ... -->
  </properties>

  2. In cms-dependencies/pom.xml, add the Commerce Open UI Pickers module dependency:

      <dependencies>
    <!-- ... -->
    <dependency>
      <groupId>com.bloomreach.commercedxp</groupId>
      <artifactId>starterstore-frontend-ng</artifactId>
      <version>${starterstore.version}</version>
    </dependency>
    <!-- ... -->
  </dependencies>

Configure Commerce Open UI Pickers

Start your project and configure the pickers using the CMS Console.

Commerce Category Picker Configuration

Import the following YAML under /hippo:configuration/hippo:frontend/cms/ui-extensions:

/commerceCategoryPicker:
  jcr:primaryType: frontend:uiExtension
  frontend:extensionPoint: document.field
  frontend:displayName: Commerce Category Picker
  frontend:initialHeightInPixels: 80
  frontend:url: angular/starterstore/index.html?id=categories
  frontend:config: "{\r\n  \"apollo.server.url\": \"http://localhost:4000/graphql\"\
    ,\r\n  \"field.connector.id\": \"myproject:connectorid\"\r\n}"

Parameters in frontend.config:

ParameterDescription
apollo.server.urlURL of the brX GraphQL Service
field.connector.idJCR property name for the Commerce Connector ID
default.connector.id(Optional) Default connector ID header value (e.g., brsm)

Update the field names if your project uses different properties.

Commerce Product Picker Configuration

Import the following YAML under /hippo:configuration/hippo:frontend/cms/ui-extensions:

/commerceProductPicker:
  jcr:primaryType: frontend:uiExtension
  frontend:extensionPoint: document.field
  frontend:displayName: Commerce Product Picker
  frontend:initialHeightInPixels: 300
  frontend:url: angular/starterstore/index.html?id=products
  frontend:config: "{\r\n  \"apollo.server.url\": \"http://localhost:4000/graphql\"\
    ,\r\n  \"field.connector.id\": \"myproject:connectorid\"\r\n}"

Parameters in frontend.config:

ParameterDescription
apollo.server.urlURL of the brX GraphQL Service
field.connector.idJCR property name for the Commerce Connector ID
default.connector.id(Optional) Default connector ID header value (e.g., brsm)

Update the field names if your project uses different properties.

Commerce Product Variant Picker Configuration

Import the following YAML under /hippo:configuration/hippo:frontend/cms/ui-extensions:

/commerceProductVariantPicker:
  jcr:primaryType: frontend:uiExtension
  frontend:extensionPoint: document.field
  frontend:displayName: Commerce Product Variant Picker
  frontend:initialHeightInPixels: 300
  frontend:url: angular/starterstore/index.html?id=product-variants
  frontend:config: "{\r\n  \"apollo.server.url\": \"http://localhost:4000/graphql\"\
    ,\r\n  \"field.connector.id\": \"myproject:connectorid\",\r\n  \"\
    field.product.id\": \"myproject:productid\"\r\n}"

Parameters in frontend.config:

ParameterDescription
apollo.server.urlURL of the brX GraphQL Service
field.connector.idJCR property name for the Commerce Connector ID
field.product.idJCR property name for the Product ID
default.connector.id(Optional) Default connector ID header value (e.g., brsm)

Update the field names if your project uses different properties.

Add the Category Picker Field to a Document

To add a Category Picker field to the news document type:

  1. Edit the document type and add an Open UI String field.

  2. Set the ui.extension property of the field to commerceCategoryPicker.

    Document type editor with Open UI String field option highlighted

    Bloomreach document editor showing commerceCategoryPicker field configuration

  3. Add a Dropdown field to the document type. For demonstration, use a Static Dropdown with:

    • Path: connectorid
    • selectable.options: brsm=Bloomreach,commercetools=Commercetools

    Document editor with Commerce Connector dropdown and category browser

  4. Save and commit the document type changes.

Verification

  1. Edit a news document.

  2. Select a Commerce Connector in the dropdown field.

  3. Click the Browse categories... button.

    News document editor with Commerce Connector and Browse categories button

  4. Browse the Commerce Categories tree and select a category.

    Category selection dialog with commerce category tree and Select button

  5. Click Select and verify that the selected category appears in the document.

Add Product Picker and Product Variant Picker Fields to a Document

To add Product Picker and Product Variant Picker fields to the events document type:

  1. Edit the events document type.

  2. Add an Open UI String field and set ui.extension to commerceProductPicker.

    Document type editor showing Event fields and field palette

    Document type editor with ui.extension set to commerceProductPicker

  3. Add another Open UI String field and set ui.extension to commerceProductVariantPicker.

    Document type editor showing Product Variant field UI extension

  4. Add a Dropdown field to the document type. For demonstration, use a Static Dropdown with:

    • Path: connectorid
    • selectable.options: brsm=Bloomreach,commercetools=Commercetools

    Bloomreach XM document type editor with commerce connector dropdown

  5. Save and commit the document type changes.

Verification

  1. Edit an events document.

  2. Select a Commerce Connector in the dropdown field.

  3. Use the Select buttons for product or product variant fields.

    Bloomreach Content event document editor showing selected commerce product

  4. Search for and select a product or product variant.

  5. Click Select and verify that the selection appears in the document.

For more details on the brX GraphQL Service or Open UI Pickers, refer to the Commerce GraphQL Service documentation.

Share Feedback
Page: /frontend/open-ui-extensions/configure-open-ui-pickers-from-scratch
Section: Frontend
Category *