Broadleaf Microservices
  • v1.0.0-latest-prod

Component Registrar

Overview

The ComponentRegistrar is a repository of the named and common components used to support the metadata-driven views and forms within the admin. This document gives an overview of how it can be used to customize the admin web application.

Named Components

Named components have 5 categories and are referenced directly from metadata using their type and classifier. Metadata is interpreted by the <ComponentRenderer> and its specific derivatives, <ViewTypeRenderer>, <FieldTypeRenderer>, <GroupTypeRenderer>, and <ExternalTypeRenderer>, <ColumnTypeRenderer> to determine what component to render.

Component Renderers

Renderers

Classifiers and Example Types

  • Views (or forms)

    • Used for both top-level views and sub-views within other view components

    • Usually mapped to a URL path like the Product update view

    • e.g., ENTITY (for updates and creates), ENTITY_BROWSE (lists all entities of a type like all Products)

  • Groups

    • Related fields visually grouped together in a view/form

    • e.g., COLLAPSIBLE, BASIC, INLINE

  • Fields

    • Form fields representing properties on an entity like Product name and SKU

    • e.g., STRING, BOOLEAN, DATE

  • Externals (fields)

    • Form fields representing external references that use a different API endpoint than the main entity like Variants shown on the Product update view.

    • e.g., EXTERNAL_GRID

  • Columns

    • Used for rendering the columns usually in a <ListGrid> component.

Rendering Examples

The renderer components are provided a metadata prop, which in turn delegates to ComponentRenderer and ComponentRegistrar for retrieving the correct React component and rendering it, for example:

// rendering this
<ViewTypeRenderer
  metadata={{
    classifier: 'View',
    type: 'ENTITY',
    // ...
  }}
/>

// will end up rendering this
<EntityView />

Registering Components

A component can be registered with the ComponentRegistrar in order to support a new metadata-driven component, or override an existing one.

Registering Views

A new view may be registered using registerViewComponent:

import { services } from '@broadleaf/admin-components';
const { ComponentRegistrar } = services;

// override the default "ENTITY" view
ComponentRegistrar.registerViewComponent('ENTITY', MyEntityView);

// register a new specialized view
ComponentRegistrar.registerViewComponent('CUSTOM_VIEW', MyCustomView);

View components should expect to receive a metadata prop with the provided metadata:

const MyView = ({ metadata }) => {
  // render something
}

A top-level view component is rendered with routing information provided by the route:

const TopLevelView = ({
  history,
  location,
  match,
  metadata,
  route
}) => {
  // render something
}

View components are at times rendered within a view component itself, and these sub-view components may receive any number of props:

const SubView = ({
  customProp,
  metadata
}) => {
  // render something
}

Registering Form Components

Form components may be registered using registerFieldComponent, registerExternalComponent, and registerGroupComponent.

import { services } from '@broadleaf/admin-components';
const { ComponentRegistrar } = services;

// override the default "STRING" field
ComponentRegistrar.registerFieldComponent('STRING', MyStringField);

// register a new specialized field
ComponentRegistrar.registerFieldComponent('CUSTOM_FIELD', MyCustomField);

Form components should expect to receive both of metadata prop, and a formik prop (see Formik library to learn more about managing form state):

const MyField = ({ formik, metadata }) => {
  // render something
}

While all form components receive similar props, there are key differences in their behavior and functionality. Field components rendered by FieldTypeRenderer are used to interact with the formik state. Group components rendered by GroupTypeRenderer are used for presentation, and generally do not interact with formik state. External components rendered by ExternalTypeRenderer are used for interacting with external services and APIs.

A collection of form components can be rendered using FormComponents:

import { Formik } from 'formik';
import { components } from '@broadleaf/admin-components';
const { FormComponents } = components;

const MyView = ({ metadata }) => {
  return (
    <Formik>
      {formik => <FormComponents components={metadata.components} formik={formik} />}
    </Formik>
  );
}

Common Components

Common components are those which are not directly referenced from metadata but are referenced internally by other components. Examples of this are the basic <Button>, <Currency>, <Hint> components that are reused throughout the component library. Override these the same way as named-components as discussed in the previous section, Registering Form Components.

Tip
 They have names like blButton, blCurrency, and blHint and do not need any specific classifier. 
import { services } from '@broadleaf/admin-components';
const { ComponentRegistrar } = services;

ComponentRegistrar.registerComponent('blButton', MyCustomButton);