Broadleaf Microservices

Component Registrar

The ComponentRegistrar is a repository of the named 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.

Usage

The ComponentRegistrar is used to store React components by a classifier and type key. The registrar is used within several renderer components to retrieve React components that match certain metadata.

Renderers

There are four classes of registered components: View, Field, Group, and External. View components are used for both top-level views and sub-views within other view components. Field, Group, and External components are form components that are used to render forms within various views. Column components are used for rendering the columns within a list grid.

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
  metadata={{
    classifier: 'View',
    type: 'ENTITY',
    // ...
  }}
/>

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