Broadleaf Microservices
  • v1.0.0-latest-prod

Unstable Exports Bundle

The reason these are exported is to support edge cases where the usage of these exports for hot-fixes or workarounds could save significant time.

Export Package Name: unstable

How to pull in the module and its components
import { unstable } from '@broadleaf/admin-components';

const { FulfillmentItemUtils } = unstable;

Application Package

Component Name Description

AdminApp

The root component representing the entry point to the app. It provides the base layout and page routing.

AdminAppProps

The interface type used to strictly identify the data passed via props for AdminApp.

AdminProvider

A composite component that configures the various global React Context Providers such as TrackingContextProvider.

AdminProviderProps

The interface type used to strictly identify the data passed via props for AdminProvider.

GlobalProviders

A set of global Provider components that are necessary for the basic functions of the Admin application and are accessible from every route. See the list and detailed explanation of each global Provider here.

GlobalProvidersProps

The interface type used to strictly identify the data passed via props for GlobalProviders.

export interface GlobalProvidersProps {
  /**
   * The set of providers to render by this component.
   *
   * @see GlobalProviders.defaultProps.providers for the default set of providers
   */
  providers: Array<any>;
}

Authentication Package

Component Name Description

AuthCache

This component is used to store results from auth flows, like the resolved AuthorizedClient, in the browser cache storage.

AuthContext

The context used for providing the user and authentication state to the Admin application. This context is initialized in AuthGateway

AuthService

A service used for various authentication functions, such as checking tokens, getting authenticated user information, logging in and out, among others.

AuthStateCache

This component is used to store the state token generated during OAuth2 token retrieval flows in the browser cache storage.

ClientDiscoveryService

A service that retrieves the client information for the provided tenant, application, and type.

KeepSessionAlive

A component that renders a modal that prompts the user to either extend their session by staying logged in or kill the session by logging out.

useAuthContext

A hook used to fetch the AuthContext.

useHasAccess

A hook used to check whether the current user has access to the given scopes for the given operation types. If there is not a record with operation type information for a given scope, then this hook will request the operation data for that scope.

useHasAccessForEach

A hook used to check whether the user has access for each of the provided scope and operation type pairs. Used in useHasAccess to identify the result of the hook.

useImpersonateUser

A hook that returns a callback for initiating the impersonation flow for a user. If no username is provided, this will initiate the anonymous impersonation flow.

useIsCheckingAccess

A hook used to check whether or not the given scopes are being checked for access by the current user from UserAccessContext. Essentially just checks whether the current user is being authorized or not.

useKeepSessionAlive

A hook that either extends the user’s session if activity has occurred in a specified amount of time / if the user manually extends the session, or kills the session if no activity has occurred in a specified amount of time / if the user manually kills the session by logging out.

UserAccessContext / UserAccessDispatchContext

The context used for providing user access information & dispatching actions that change the user access state to the Admin application. This context is initialized & managed in UserAccessProvider. Read more about this context here.

UserAccessService

A service that checks for the user’s access authorization by checking the operation against their accessible scopes.

useUserProfile

A hook that fetches the current user’s profile information from the AuthContext.

UserAccess

How to pull in the module and its components
import { unstable } from '@broadleaf/admin-components';

const { actions } = unstable.UserAccess;
Component Name Description

actions

A collection of exports related to UserAccess actions.

import { unstable } from '@broadleaf/admin-components';

const { actions } = unstable.UserAccess;
const { ActionTypes } = actions;

  • ActionTypes: Action types enum for user access actions.

  • getUserOperations: Function that requests and returns user access operations.

  • requestUserOperations: Function that returns a dispatch object to request the user’s accessible operations.

  • receiveUserOperations: Function that returns a dispatch object to return the user’s accessible operations.

  • errorUserOperations: Function that returns a dispatch object to handle an error when trying to fetch the user’s accessible operations.

CheckAccess

A render prop component that checks whether the user has access to an operation for a particular scope by calling makeCheckAccess.

connectUserAccess

A wrapped component that connects the UserAccessContext & UserAccessDispatchContext contexts and whose props are mapped from the state/dispatch contexts.

makeCheckAccess

A memoized hook that compares the user’s operationTypes for their accessible scopes and returns if the user has access to any of the scopes.

reducer

A reducer that is the combined functions of the UserAccessContext & UserAccessDispatchContext contexts for fetching user access information.

useCanUserModify

A hook that returns whether the current user can modify the given component based on the component’s scopes and the user’s permissions.

useCanUserSee

A hook that returns whether the current user can see the given component based on the component’s scopes and the user’s permissions.

useCheckAccess

A hook used for getting a function to check access for a scope and operation type.

When

A component that conditionally renders something based on whether or not the user has access to an operation for a scope.

withCheckAccess

A higher-order component that provides the checkAccess function as a prop to another component.

TenantSecurityUtils

How to pull in the module and its components
import { unstable } from '@broadleaf/admin-components';

const { getDefaultApplication } = unstable.TenantSecurityUtils;
Component Name Description

getDefaultApplication

A function that returns the default application for the given user. Generally returns the a shell application where the id is the first ID in the user’s set of application restrictions.

hasApplicationAccess

A function that checks if the user has application access.

hasApplicationRestriction

A function that checks if the user has access to an application.

hasTenantAccess

A function that checks if the user has tenant access.

hasTenantRestriction

A function that checks if the user has access to a tenant.

isAdminType

A function that checks if the user is an ADMIN.

isApplicationAdmin

A function that checks if the user is an admin of an application.

isApplicationRestricted

A function that checks if the user is not linked to any applications.

isAuthorized

A function that checks whether or not the user has a type of ADMIN and is authorized to access the admin for the current tenant and application.

isAuthorizedForApplicationAdmin

A function that checks if the user is a global administrator or has access to a specific application.

isAuthorizedForDifferentApplication

A function that checks whether or not the user is authorized to access the admin for the current tenant, but for a different application. This is mainly used to engage behavior that sets the current application to their default.

isAuthorizedForGlobalAdmin

A function that checks if the user is a global administrator.

isAuthorizedForTenantAdmin

A function that checks if the user is a global administrator or has access to a specific tenant.

isTenantAdmin

A function that checks if the user is an admin of a tenant.

isTenantRestricted

A function that checks if the user is not linked to any tenants.

Collection Package

Component Name Description

ActionListGrid

A component that renders a ListGrid with a set of actions in various placements.

AdvancedSearch

A component that renders advanced search and filter components from the metadata.

AdvancedSearchQueryBuilder

A component that renders a QueryBuilder component using the initial filters and fields from the metadata.

CollectionStateHook

A collection of exports related to CollectionStateHook.

import { unstable } from '@broadleaf/admin-components';

const { CollectionStateHook } = unstable;
const { actionCreators } = CollectionStateHook;

  • actionCreators: Collection of functions that mutate, read, select, sort, or filter pagination items and pages.

  • CollectionActionTypes: Collection of action types that represent the pagination actions.

  • initialState: The initial object for the collection state.

  • selectAllItems: A function that returns an array of all items on all pages.

  • selectAllSelectedIds: A function that returns an array of IDs of all selected items on all pages.

  • selectAllSelectedItems: A function that returns an array of all selected items on all pages.

  • selectCurrentItems: A function that returns an array of all items on the current page.

  • selectCurrentPage: A function that returns the current page.

  • selectFilter: A function that returns an applied filter that matches the passed predicate.

  • selectFilters: A function that returns all filters or all filters that match the passed predicate.

  • selectIsPageEmpty: A function that returns if the current page is empty.

  • selectIsSelectAll: A function that returns if all items on all pages are selected.

  • selectIsSelectNonVisible: A function that returns if there are any items on non-current pages that are selected.

  • selectIsSelectVisible: A function that returns if all items on the current page are selected.

  • selectItem: A function that returns an entity whose ID matches the passed ID.

  • selectPaginateProps: A function that returns pagination props such as if the current page is the first or last, and the passed onPageChange function

  • selectSelectedCount: A function that returns the total number of selected IDs across all pages.

  • selectSelectedIds: A function that returns all IDs of selected items on the current page.

  • selectSelectedItems: A function that returns all selected items on the current page.

  • selectSorts: A function that returns all sorts or all sorts that match the passed predicate.

  • useCollectionState

defaultFilterReducer

The default reducer for filter types to return modified state objects matching that filter type’s filter parameters.

defaultSortReducer

The default reducer that reduces the sorts to the expected string params, chained with a semi-colon.

FilterType

The set of filter types used within various collections.

ListGrid

Renders a table based on the provided headers and rows. This is the primary method for rendering tabular data within the admin.

PaginateState

A collection of exports related to PaginateState.

import { unstable } from '@broadleaf/admin-components';

const { PaginateState } = unstable;
const { createPaginateActions } = PaginateState;

  • createPaginateActions: Action generator that yields the set of action creators and action types for use with the createPaginateReducer reducer.

  • createPaginateReducer: Reducer creator that yields a reducer function used for maintaining state for a paginated result set. This will support non-paginated result sets if the actions provide an unpaged response as well.

  • defaultActionTypes: Collection of action types that represent the pagination actions.

  • initialPageState: The initial object for the page state.

  • initialPaginateState: The initial object for the pagination state.

  • validateActionTypes: Validates that the set of action types provided include the action types expected. This will throw an InvariantViolation if any of the expected action type are missing.

PagingType

The collection of pagination types.

PagingUtils

See PagingUtils.

QueryBuilderTypes

The collection of QueryBuilder types.

useAdvancedSearch

A hook that sets up the state management used alongside the AdvancedSearch component. It is designed to manage state for multiple sets of filters. State is initialized based on provided action definitions, and it returns the current state and an onFiltersChange function for updating the values.

useCollectionState

See useCollectionState.

useImportCollection

A hook used for managing the pagination state & handlers for ImportMaintenance.

Common Package

Component Name Description

ActionLink

A component that renders a Link component with its default behavior prevented. This is intended to be used when you need to present something as a link, but want a custom onClick behavior.

ActionLinkCollapse

A component that renders an ActionLink that hides/shows collapsible content.

ArrayState

A stateful render prop component that is useful for managing array state in both paginated and non-paginated scenarios. This component provides as a render prop both the array state and its bag of useful methods for managing the array state.

AssetDropzone

A component used to provide a dropzone for uploading files and assets.

AssetPreview

A component that renders a preview of the type of asset at the provided src.

axios

A utility helper class that uses the Axios library to create a new HTTP client instance with a custom configuration.

batchActions

A function that returns an object that contains the passed batching actions, the BATCH type, and the attribute to signal that this is to be used for batching.

bindActionCreators

A function that binds given action creators to a given dispatch context.

Button

A component that renders a custom styled button according to the passed props.

ButtonGroup

A container for a set of buttons that provides a grouped look and feel to the buttons.

Card

A component used for rendering the content for a card with a header and body.

Checkbox

A component that renders a custom styled checkbox according to the passed props.

ClickOutside

A purely control component that provides utility for managing toggle state.

CollapseGroup

A component that renders a collapsible group that is primarily used in forms for grouping fields visually.

ColorUtils

A collection of exports related to ColorUtils.

import { unstable } from '@broadleaf/admin-components';

const { ColorUtils } = unstable;
const { convertColorToRgb } = ColorUtils;

  • convertColorToRgb: If the color is an rgb, hsl, hex, or CSS-named color, returns an RGB object for that color, or returns null otherwise. This is accomplished by attaching the color to a temporary DOM element and reading the compute color.

  • getForegroundColor: Determines whether dark or light is a better foreground color given a background color based on brightness calculation.

  • isValidColor: Returns true if the color is an rgb, hsl, hex, or CSS-named color.

ColumnHeader

A component that renders a simple, read-only view of a column header.

ColumnProperties

Contains a function named columnTypeName that returns a concatenated string using the passed type string, the COLUMN_TYPE_PREFIX and COLUMN_TYPE_PREFIX_SEPARATOR .env properties.

combineReducers

A function that turns an object whose values are reducers into a singular reducer function. Note: This emulates the behavior of redux’s `combineReducers` function.

ComponentRegistrar

A service that manages components for the metadata-driven rendering of the application.

ComponentRenderer

This component renders metadata-driven components. This renderer can be used when a component has to render multiple components based on metadata of varying classifiers. Read more about all types of renderable components in the Metadata exports page.

ConditionalHelper

See ConditionalHelper.

ConfirmModal

This component is used to show a confirmation prompt before executing an action. It is usually used when deleting an entity.

Currency

A component that renders a decimal value formatted into a currency field.

DatePicker

A component that renders a date picker component to allow users to choose a date and time.

DateTime

A component that renders a formatted date and time in a friendly, locale-relative, manner. It can optionally also format the date and time as relative to 'now': 10 seconds ago, 1 day ago, etc.

Dropdown

The component used for displaying a list of menu items.

enableBatching

A function that enables batching for the provided reducer. See the redux-batched-actions Github repo for more details.

enableOverrides

A function that enables a component to be overridable.

Environment

A utility helper class that provides methods for resolving environment properties.

ErrorTrace

A component that renders the error message and stack trace for both API and application errors. Typically this is rendered in the footer of ViewStatus.

ErrorType

A render prop component that is used to format errors when requests or processes fail.

HeaderBar

A component that renders a header bar that wraps around the passed children commponents.

HelpText

A component that renders an explanatory message that appears when a help icon (?) is clicked. This component only requires a message. The message may contain HTML markup.

Hint

A component that renders an explanatory message that appears beneath another element. This component requires only a message.

HTMLEditor

A component that renders an HTML editor field that allows users to switch between Editor (uses DraftJS to visualize the HTML elements) and HTML (plain HTML text) views.

I18nContext

The context used for providing the current and available locales for the application. This context is initialized in I18nProvider. Read more about this context here.

I18nProvider

This component renders the I18nContext and wraps it around the children components to provide access to the current and available locales for the Admin application.

IconButton

A component that renders an icon button that matches the passed props.

Image

A component that renders an image that matches the passed props.

InlineError

A component that renders an inline error within a alert pre-block.

Link

A component that renders a link that matches the passed props.

ListGrid

Renders a table based on the provided headers and rows. This is the primary method for rendering tabular data within the admin.

LocalStorageCache

A class that allows the creation of instances to store and access elements within the browser local storage as a cache. Instances of this class handle the syncing between the local JS cache and browser local storage.

log

A utility helper class that implements a simple logging library that extends `console’s logging methods using level-based logging and filtering, except the class adds custom decorations to the log statements.

mapper

A utility helper class that takes in a source object and a set of mappings, and returns the result of applying the mappings to the source object.

Modal

A component that renders a modal within a portal.

Numeric

A component that renders a given number formatted in a friendly, locale-relative, manner. Additional formatting props can also be provided and will be passed to the internal formatter component(s).

poll

A function that begins interval polling using the provided promiseFactory. This will execute on the interval set in options.interval, which defaults to 150 ms.

Portal

A component that renders its children inside a container element within the DOM.

Prompt

A render prop component that is used for handling a location blocking prompt. This is primarily useful for dirty form states to ensure that the user doesn’t accidentally lose important form data. Note: This component MUST be rendered within a Router.

requestError

Contains a function named getErrorMessage that returns the error message from a given error object.

Ribbon

A component that renders a ribbon filling the full width of its container with a shallow height. This component is primarily used by SandboxRibbo and CatalogRibbon components.

SanitizeHTML

The helper component for displaying the sanitized HTML to prevent XSS.

ScrollView

A component that renders the header and scrollable content panel of the application.

SelectableType

A collection of exports related to SelectableType.

import { unstable } from '@broadleaf/admin-components';

const { SelectableType } = unstable;
const { convertColorToRgb } = SelectableType;

  • canExclude: Returns whether or not the grid allows the user to exclude items from the select all.

  • canSelectAll: Returns whether or not the grid allows the user to select all items.

  • canSelectMultiple: Returns whether or not the grid allows the user to select multiple items.

  • is: A collection of enums to determine what the selectable type for a grid is.

shallowEqual

A function that shallowly compares two objects to see if they are equal.

SimpleIcon

A component that renders an icon that matches the passed props.

SimpleModal

A component that renders a simple modal that matches the passed props.

Spinner

A component that renders a spinner using only CSS for the display.

strictEqual

A function that strictly compares two objects to see if they are equal.

SubmissionError

A component that renders a tooltip error when a submission error occurs.

SVG

A component for utilizing icons within the Admin. The current implementation uses the icons from the Zondicon icon pack.

thunkMiddleware

Thunk middleware for usage with useEnhancedReducer or other middleware-supported reducer patterns. This middleware enhances dispatch to support thunks for action creators. Read more about thunks on the Redux website.

Toast

A component that renders a toast notification that matches the passed props.

ToastContainer

A component that acts as a container for toast notifications and facilitates their transitions/animations.

ToastContainerContext

The context used for providing the toast state and actions such as adding or removing toasts to the Admin application. This context is initialized & managed in BaseLayout. Read more about this context here.

Toggle

A purely control component that provides utility for managing toggle state.

Tooltip

A component that renders a message that is only revealed when an element is in a particular state, typically hovered or focused. This component requires a message and controlTag (the component the tooltip is for) which it wraps in a containing tag to ensure correct positioning.

useActionCreators

A hook used to bind action creators to a dispatch context.

useAssetDropzone

A hook used for instrumenting an asset dropzone component.

useCancelTokenFactory

A hook used to initialize a cancel token in a mutable ref object that can be used for cancelling requests. Any requests using the cancel token will be cancelled on cleanup.

useConfirmModal

A hook which is used to connect to the state of the confirm modal dialog.

useDebouncedCallback

A hook used to return a debounced callback (a memoized function that will only invoke the callback function when the delay period has passed since the last invocation).

useDeferred

A hook that provides a delay upon component mount.

useEnhancedReducer

A hook used to return an enhanced useReducer hook which supports custom Redux-like middleware as the third parameter.

useEventCallback

A hook used to create an event callback that will not change with every render. This is necessary in situations where you want to pass an event callback as a prop without resulting in re-renders of children components.

useForceUpdate

A hook whose returned callback will force the component to re-render.

useFormatDate

A hook that wraps react-intl useIntl() and returns only the formatDate function.

useFormatMessage

A hook that wraps react-intl useIntl() and returns only the formatMessage function.

useFormatNumber

A hook that returns a function that will localize a number.

useFormattedMessages

A hook that takes in a map of Message Descriptors and returns a map whose values are the formatted messages.

useFormatTime

A hook that wraps react-intl useIntl() and returns only the formatTime function.

useInterval

A hook used to execute a callback on an interval. This hook uses a self-adjusting timer to properly handle delays in browser activity due to events such as browser inactivity.

useIsMounted

A hook that returns a boolean that indicates whether or not the component using it is mounted.

useLocationCache

A hook used to synchronize a key-value pair with the location state. When the value changes, the location is replaced with the current value, and pushed with the next value.

useOnCaptureOutside

A hook used to trigger a handler whenever a click is made outside of a capturing component. The returned callback should be passed to the "capture" handler of the container component for the expected events.

useOnEscapeKeyDown

A hook used to attach the passed handler to run anytime a 'keydown' event is triggered.

usePollEffect

An effect hook used to execute the provided function on an interval. The interval strategy is determined by the options.strategy parameter, which is defaulted to poll every second.

usePrevious

A hook used for getting a value from the previous render.

useRefreshEffect

An effect hook used to implement fetch behavior on mount or in reaction to changes in dependencies.

useToastContainer

A hook used to provide the state and helper functions for managing toasts. This hook is used in BaseLayout to help initialize the ToastContainerContext.

useUploadAsset

A hook used for providing state management for the lifecycle of a single-file asset upload.

Form Package

Component Name Description

ColumnTypeRenderer

This component renders metadata-driven column components of classifier "Column". Read more about all types of renderable column components in the Columns Metadata exports table.

connectTreeView / TreeView

A function that returns a component wrapped in the TreeView context and dispatch contexts.

DefaultValueService

A service that manages and returns default values for fields across the application.

DownloadLink

A component which is used to render HTML hyperlinks.

ExternalTypeRenderer

This component renders metadata-driven external components of classifier "External". Read more about all types of renderable external components in the Externals Metadata exports table.

FieldDecorations

A helper class to render decorations around supplied children components, typically just an input.

FieldError

A component that renders a field validation error.

FieldTypeRenderer

This component renders metadata-driven field components of classifier "Field". Read more about all types of renderable field components in the Fields Metadata exports table.

FormComponent

This component renders metadata-driven form components. This component makes use of component renderers such as FieldTypeRenderer and ExternalTypeRenderer, among others.

FormComponents

This component renders the set of Form Components driven by a set of metadata components.

FormikError

A component that renders an error icon with a tooltip for the errors from a Formik submission.

GroupTypeRenderer

This component renders metadata-driven group components of classifier "Group". Read more about all types of renderable group components in the Group Metadata exports table.

ItemBrowser

A collection of exports related to ItemBrowser.

import { unstable } from '@broadleaf/admin-components';

const { ItemBrowser } = unstable;
const { Display } = ItemBrowser;

  • Display: Returns an ItemBrowser component, which is used to display item-based and/or foldering views.

  • Modals: Returns a component that renders all modals that are related to ItemBrowser actions.

  • Provider: Returns a provider component used to set up the ItemBrowserStateContext, ItemBrowserDropzoneContext, ItemBrowserHandlerContext, ToastContainerContext, and ItemBrowserDispatchContext for downsteam components to consume.

Label

A component that renders a <label> element within translated message content. Supports an optional helpText prop for displaying a help icon (?) with the help text inside.

Lookup

A component that renders a react-select lookup field.

lookupComponents

A collection of component exports related to Lookup.

import { unstable } from '@broadleaf/admin-components';

const { lookupComponents } = unstable;
const { Header } = lookupComponents;

  • Header: Renders the lookup header.

  • Footer: Renders the lookup footer.

  • LookupContainer: Renders the container for the lookup.

  • Modal: Renders a modal that allows the user to select the value/s for the lookup via a paginated view.

  • ModalToggle: Renders the toggle for the lookup modal.

  • Select: Renders the react-select select field.

  • SelectContainer: Renders the react-select select field container.

lookupExtensions

A collection of extension exports related to Lookup.

import { unstable } from '@broadleaf/admin-components';

const { lookupExtensions } = unstable;
const { ProductSelect } = lookupExtensions;

  • ProductSelect: Renders a component that is intended to be used as a replacement for the default Select component used for a Lookup. This component builds on top of the default to enhance the single-value, multi-value, and option displays to show additional information about the Products.

ModalForm

A component that is used for rendering a form within a modal. This is primarily used when creating or editing items within a collection.

ModalFormAction

A component that renders an action component that opens a ModalForm. This is the typical way a ModalForm ends up being rendered by collections.

Request

See Request Utilities.

RequestAgentContext

A context that combines the request functions found in Request Utilities.

RequestErrorUtils

A collection of component exports related to Request errors.

import { unstable } from '@broadleaf/admin-components';

const { RequestErrorUtils } = unstable;
const { clearFormikErrors } = RequestErrorUtils;

  • clearFormikErrors: A helper method to normalize how we’re resetting formik.status of submission errors and resetting formik.errors.

  • getFormikErrorMessages: Returns readable error messages from the given formik instance. This will provide error messages from a combination of the field-level and any global error messages if they exist.

  • getResponseFieldErrors: Get submission errors in a Formik readable shape.

  • getResponseGlobalErrors: Get all readable error messages from the response’s global errors.

  • joinErrorsWithReason: A helper method to map over error response messages for a specific field.

  • setFormikErrors: Set formik status and errors for the provided error response. This handles the following scenarios:

    1. Field-level submission errors.

    2. Global-level submission errors.

    3. Error message given with response.

    4. Request errors caused by pre-request failures (e.g. errorResponse is an error string).

RSQLOperatorsProvider

Registers all RSQL-related providers and operators.

SchemaService

A service that manages and handles Yup Validation schema operations, providers, and constants.

SpELComposersProvider

egisters all SpEL-related providers that are used to compose the QueryNode for a RuleBuilder.

SpELOperatorsProvider

Registers all SpEL-related providers and operators.

SpELParsersProvider

Registers all SpEL-related parsers for parsing SpEL expressions.

SpELQueryNode

This class is used to build SpEL expressions.

ToggleSwitch

A component that renders as a group of radio like buttons where the user can toggle one at a time, whether through tapping/clicking or cycling with focus and the keyboard.

ToggleSwitchGroup

A component that renders a collapsible group that is used in a sentence format with the ToggleSwitch.

translateModeActions

A collection of action exports related to TranslateMode.

import { unstable } from '@broadleaf/admin-components';

const { translateModeActions } = unstable;
const { ActionTypes } = translateModeActions;

  • ActionTypes: The action types for setting the locale.

  • setLocale: A function that sets the translate mode to active with the provided locale code. If the locale code is null or undefined, this will mark the translate mode as inactive.

  • SetLocaleDefinition: The return type for setLocale.

TranslateModeContext / TranslateModeDispatchContext

The context used for providing the state for the Translate Mode functionality to the Admin application. This context is initialized & managed in TranslateModeProvider. Read more about this context here.

TranslateModeProperties

Returns the static and environment properties related to TranslateMode, such as request headers and the locale context parameter name.

TranslateModeProvider

This component renders TranslateModeContext and wraps it around the children components to provide access to the state for the Translate Mode functionality for the Admin application.

translateModeReducer

The reducer for the actions related to TranslateMode.

TranslateModeService

A service that manages and gets the translations for the given metadata and form values.

TranslateModeUtils

A function that creates a Translation object with entityField and value.

treeActions

A collection of action types and action creators that perform actions related to the TreeView component.

TreeViewContext

The React context for the TreeView component. This is used for organizing and managing the hierarchical item set for the component.

TreeViewDispatchContext

The context used for dispatching actions that change the tree view state. This is primarily implemented by TreeViewProvider.

TreeViewProvider

The primary state provider for TreeViewContext components. This component contains the functionality to dispatch actions and reduce them into it’s state. This must be rendered as an ancestor of any tree view related components and should generally be the single source of truth for these component’s state.

treeViewReducer

Returns a reducer that handles all TreeView actions.

UnsavedChanges

A component that renders the unsaved changes messaging if the dirty flag is true.

useAssetDropzoneField

The hook for AssetDropzoneField.

useExternalCollection

A hook used for instrumenting the useCollectionState hook and configuration of an ActionListGrid component for an external collection within a form.

useTranslateMode

A hook used to return the Translate Mode state from TranslateModeContext with a helper method to set the Translate Mode locale.

Gateway Package

Component Name Description

AuthGateway

This gateway component is responsible for being a "gateway" before rendering the application. It first discovers the OAuth2 client, checks the authentication of the user, and verifies if the user is authorized to access the current tenant and application. If the authentication was successful, it will initialize the authentication context and render its children components.

ComponentRouter

This component initializes routes for the Admin gateway. When ready, this will fetch the routes and provide them to children components through the ComponentRouterContext.

GatewayProvider

This component is responsible for taking in a set of GatewayComponent components and recursively rendering these in order to derive the set of gateway state objects. The gateway state objects are then used in rendering the loading view while gateway resolution is in-progress, and then the children components are rendered once all GatewayComponent components are finished with their verification processes.

TenantGateway

This gateway component retrieves the tenant information and provides the TenantContext around the wrapped components. Read more about tenant & application resolution in this Tenant Resolution Walkthrough.

useGatewayState

The hook used for providing the state for the gateway status that is used by each gateway interface.

Metadata Package

Component Name Description

ActionRegistrar

A service used for registering and accessing custom Action components for various metadata-driven components.

AttributeUtils

A collection of exports related to metadata attributes.

import { unstable } from '@broadleaf/admin-components';

const { AttributeUtils } = unstable;
const { getAttributePath } = AttributeUtils;

  • getAttributePath: Gets the attribute property path given the provided attribute name and attributes property name. This will return the Attribute path, not the value path.

  • getAttributesPropertyName: Gets the attributes property name from the provided container metadata. We have three ways of resolving this property name:

    1. From attributes.customAttributesProperty on the container metadata.

    2. From import.meta.env.CUSTOM_ATTRIBUTES_PROPERTY_NAME as a system property.

    3. The default of "attributes", which is most commonly the correct name. If the locale code is null or undefined, this will mark the translate mode as inactive.

  • getAttributeValuePath: Gets the attribute value property path given the provided attribute name and attributes property name.

AugmentationControls

A component that allows the user to toggle the augmentation mode for customizing form fields via the Admin application.

AugmentationUtils

A collection of exports related to augmentation.

import { unstable } from '@broadleaf/admin-components';

const { AugmentationUtils } = unstable;
const { createAugmentation } = AugmentationUtils;

  • createAugmentation: A function that makes a request to create an augmentation.

  • getAugmentationScope: A function that gets the augmentation URL from the environment variables.

  • getAugmentationUrl: A function that gets the augmentation scope from the environment variables.

  • undoAugmentation: A function that makes a request to delete/undo an augmentation.

ComponentRoute

A component that renders the route and route resolve for a specified component.

ComponentRouterCache

This component is used to store metadata structures retrieved from the Metadata Microservice in the browser cache storage.

ComponentRouterContext

The context used for providing the current set of metadata component routes to the Admin application. This context is initialized in ComponentRouter. Read more about this context here.

ComponentRouteResolver

The component responsible for resolving the component metadata for a route.

ComponentRouterUtils

A collection of exports related to component routing.

import { unstable } from '@broadleaf/admin-components';

const { ComponentRouterUtils } = unstable;
const { cacheComponentMetadata } = ComponentRouterUtils;

  • cacheComponentMetadata: Puts the passed component’s metadata into the browser cache storage.

  • cacheRoutes: Puts the passed routes into the browser cache storage.

  • ComponentRouterCache: This component is used to store the component router data in the browser cache storage.

  • createLocationFromLink: Builds the location of the targeted route. This makes use of https://github.com/pillarjs/path-to-regexp to compile the provided path and construct the correct pathname using any provided params. Additionally, this will include the object or string search as search parameters.

  • fetchComponentMetadata: Fetches the component’s metadata from the metadata service.

  • fetchRoutes: Fetches all routes from the metadata service.

  • getCachedComponentMetadata: Gets the cached component metadata based on the passed component ID.

  • getCachedRoutes: Gets the saved routes from the browser cache storage.

  • getMatchingRoutes: Finds the routes that match at least one of the provided URLs.

  • getNamedComponentMetadata: Returns a default metadata object for a named component.

  • hasCachedComponentMetadata: Checks if there is cached component metadata based on the passed component ID.

  • routeLinkToLocation: Gets the location of the component route from the set of routes using the provided componentId to filter down the routes to find the matching one.

ComponentRouteSplash

A component used for rendering the splash view for the route while it is loading metadata.

devSettingsActions

A collection of action creators and action types for toggling developer settings.

DevSettingsContext

The context used for storing various settings for developer tools, which are only available during development mode. This context is initialized & managed in DevSettingsProvider. Read more about this context here.

DevSettingsModal

A modal that displays the developer settings for the Admin application.

DevSettingsProvider

This component renders the DevSettingsContext and wraps it around the children components to provide access to the developer settings for the Admin application.

devSettingsReducer

Returns a reducer that handles all developer settings actions.

MetadataBoundary

This component is wrapped around metadata-driven components to render decorations, augmentations, or errors.

MetadataContext

The context used for providing the metadata state for the current view. This context is initialized & managed in ComponentRouteResolver. Read more about this context here.

metadataInvariant

A function that triggers an error if a component is missing key metadata information.

MetadataUtils

A collection of utilities for interacting with metadata.

RequestUtils

See Request Utilities.

useActions

A hook used for retrieving the typed action definitions and their components from a given metadata object.

useBackLocation

Returns the location that will take the user to the expected previous location.

useHasMatchingRoute

Checks whether or not the provided path matches a route that the current user can access.

Two requirements must be met for this hook to return true:

  • Path matches an existing route

  • User has access to the matching route

useRouteLink

A hook used to connect to the set of routes and creating a link to a route’s location based on the provided link to/from a component. This hook uses ComponentRouterContext to return the latest set of routes.

useVisibleActionDefinitions

Retrieves the action definitions from the provided metadata that are visible to the current user.

Tracking Package

Component Name Description

CatalogCache

This component is used to store the resolved catalog data in the browser cache storage.

CatalogContext

The context used for providing the current global catalog state to the Admin application. This context is initialized & managed in TrackingContextProvider. Read more about this context here.

CatalogRibbon

This component renders a "ribbon" or a bar with a button that displays a list of available catalogs for the current site, enabling filtering of entities by the selected catalog for the site. Typically rendered above a Title Bar component and below the SandboxRibbon.

CatalogSelector

A component that allows the user to select a Catalog, and updates the Formik state and/or Catalog context. This component is rendered on CREATE forms for catalog and/or profile discriminated entities, and defaults to the stored catalog ID in the existing context if one is present.

CatalogUtils

A collection of utility functions related to catalog.

import { unstable } from '@broadleaf/admin-components';

const { CatalogUtils } = unstable;
const { appendUndoOverridesAction } = CatalogUtils;

  • appendUndoOverridesAction: Renders the "Undo Overrides" button.

  • getUndoOverridesEndpoint: Fetches the endpoint for undoing any production-level catalog-override changes.

  • hasCatalogOverrides: Checks the entity’s context state to determine whether it has any production-level catalog-override changes.

  • isCatalogDiscriminated: Determines whether the given metadata contains the flag marking it for catalog discrimination. This only looks one level deep.

  • isDifferentCatalogId: Determines whether or not the current catalog ID has changed between two tracking context states.

ChangeContainerContext

The context used for providing the current set of change summaries associated with the sandboxable view to the Admin application. This context is initialized & managed in ChangeContainerProvider. Read more about this context here.

ChangeContainerProvider

This component is responsible for providing the state management functionality for a change container. This component handles providing the ChangeContainerContext, which provides the current change container state, and ChangeContainerCallbackContext, which provides a set of callback functions for updated the change container state.

ChangeHighlight

Wraps the given children in a component that renders a highlight border based on the change summaries provided. If no highlighting is needed, then returns the children unwrapped. No highlighting is needed if no changeSummaries are provided. The summaries should be provided by consuming the ChangeContainerContext.

ChangeInfoUtils

A collection of utility functions related to changes and sandboxing.

import { unstable } from '@broadleaf/admin-components';

const { ChangeInfoUtils } = unstable;
const { buildChangeInfoForEntity } = ChangeInfoUtils;

  • buildChangeInfoForEntity: Used to build the change info applicable for an entity using the given context. Returns undefined if no changes are detected for the entity.

  • buildChangeInfoForField: Used to build the change info applicable for the given field using the given context and entity.

  • CHANGE_LEVEL_TYPE: A constant that defines the significant sandbox workflow levels.

  • getFriendlyChangeTypeMessageDescriptor: Gets the message descriptor for the friendly change type key.

  • getHighlightDescriptionMessageDescriptor: Gets the message descriptor for the highlight description key.

  • getHighlightLabelMessageDescriptor: Gets the message descriptor for the highlight label key.

ChangesetAwareRow

Renders a table row as an entity that is affected by change information and change summaries.

ChangesetAwareRowHeader

Renders a table row header as an entity that is affected by change information and change summaries.

ChangeSummaryUtils

A collection of utility functions related to changes and sandboxing.

ContextRequest

A collection of exports related to context requests.

import { unstable } from '@broadleaf/admin-components';

const { ContextRequest } = unstable;
const { buildChangeInfoForEntity } = ContextRequest;

  • buildChangeContainer: Builds the change group object given the provided view container metadata and context ID.

  • ContextParameters: Constants used as keys for the different context parameters.

  • getContextRequest: Creates the JSON structure for the X-Context-Request header for the provided operationType using the global and local context states.

  • getHeaderName: Gets the header name for the context request header.

  • getInheritedContextState: Gets the inherited content state from the passed entity’s parent.

  • isEntityMutable: Returns if the entity is mutable.

ContextTypes

The available context types that a component using the withTrackingContext higher-order component can subscribe to.

LocaleContext

The context used for providing the default locale and allowed locales for the data within the resource services. This context is initialized & managed in TenantLocaleProvider. Read more about this context here.

SandboxCache

This component is used to store the resolved sandbox data in the browser cache storage.

sandboxChangeDetailsActions

A collection of functions for creating action creators for sandbox detail change actions.

sandboxChangeDetailsReducer

The reducer for the actions related to sandbox change details.

SandboxContext

The context used for providing the sandbox state with the current active sandbox and available sandboxes to the Admin application. This context is initialized & managed in TrackingContextProvider. Read more about this context here.

sandboxOperationActions

A collection of functions for creating action creators for sandbox operations.

SandboxOperationContext / SandboxOperationDispatchContext

The contexts used for providing the state of executable sandbox operations within sandboxable views. These contexts are initialized & managed in SandboxOperationProvider. Read more about these contexts here.

SandboxOperationProvider

This component renders the SandboxOperationContext and wraps it around the children components to provide access to the state of executable sandbox operations within sandboxable views for the Admin application.

sandboxOperationReducer

The reducer for the actions related to sandbox operations.

SandboxOperationType

The constants for the different sandbox operation types.

SandboxOperationUtils

A collection of utilities for executing sandbox operations.

SandboxRibbon

This component renders a "ribbon" or a bar with a button that displays a list of available sandboxes for the current user, enabling filtering of entities by the selected sandbox and current user. Typically rendered above a Title Bar component and above the CatalogRibbon.

SandboxUtils

A collection of utilities related to sandboxes.

import { unstable } from '@broadleaf/admin-components';

const { SandboxUtils } = unstable;
const { isDifferentSandboxId } = SandboxUtils;

  • isDifferentSandboxId: Determines whether or not the current sandbox ID has changed between two tracking context states.

  • isSandboxDiscriminated: Determines whether the given metadata contains the flag marking it for sandbox discrimination. This only looks one level deep.

SearchSettingsCache

This component is used to store the search settings and facet filters data in the browser cache storage.

tenantActions

A collection of functions for creating action creators for tenant operations.

TenantCache

This component is used to store the resolved Tenant and Application data in the browser cache storage.

TenantContext

The context used for providing the current tenant state with tenant and application information to the Admin application. This context is initialized & managed in TenantGateway. Read more about this context here.

TenantLocaleProvider

The component used for providing LocaleContext for a tenant-aware admin application. This should be rendered after the TenantGateway and AuthGateway components.

tenantReducer

The reducer for the actions related to the tenant state.

TenantService

See TenantService.

TrackingContextProvider

See TrackingContextProvider.

useAvailableApplications

A hook used to fetch all available applications from TenantContext.

useChangeContainer

A hook that connects to the change container context to provide the view type component change container information.

useConnectSandboxOperation

A hook used to connect to the sandbox operations actions and state.

useCurrentApplication

A hook used to fetch the currently chosen application from TenantContext.

useCurrentApplicationId

Returns the current application ID from the tenant context.

useCurrentSandbox

Returns the currently active sandbox from the sandbox context.

useCurrentTenant

A hook used to fetch the currently chosen tenant from TenantContext.

useExternalChangeContainer

A hook that connects to the change container context to provide the external type component change container information.

usePreviewChanges

A hook that creates a callback that can be used to take a user to the application to preview the changes for a sandboxed entity.

useTenantActions

A hook used to return a memoized function that allows the user to perform tenant actions such as setting the application ID, setting the tenant ID, and fetching applications, among others.

useTenantContext

A hook used to fetch the TenantContext.

useTracking

A hook used to access the catalog and sandbox tracking context and state data that is set and updated by the TrackingContextProvider. Read more about this hook here.

useUserSandboxes

Returns the current set of user sandboxes from the sandbox context.

View Package

Component Name Description

ActionBarDropdown

Renders an action dropdown menu with a button. Used for secondary action dropdowns within several views.

ApplicationSelector

A dropdown selector component that allows the user to select the current application.

Approvals

A view for rendering the list grids dealing with approving and scheduling sandbox change summaries. It also manages which grid is rendered based on the view parameter of the location search string.

AppSplash

A component used for rendering the splash screen for the application while it is loading.

AssetBrowserView

The view container component typically used for managing relationships between an entity and an Asset. This utilizes ItemBrowser for the user interface in order to allow the user to manage the asset data in various ways.

BaseLayout

This is the top-level view component that wraps all children components with the necessary providers & containers to allow certain components to be rendered over all other components or to ensure that certain components are present all-throughout the application.

Other components rendered here include the:

  • Admin Navigation sidebar;

  • the ScrollView component that renders the header and scrollable content panel of the application;

  • the ConfirmModal component and context provider that render the confirmation modals that apply to many actions across the application, such as deleting entities;

  • and Toast related components such as the ToastContainer and ToastContainerContext so that toast notifications appear above all components.

Dashboard

The component rendered at the root rout that displays the Admin Dashboard title and app version.

DefaultTreeView

A view with a TreeView component embedded in it, displaying a tree-like hierarchical view of information.

Deployments

A view for rendering the list grids dealing with managing deployments of sandbox changes. It manages which grid is rendered based on the view parameter of the location search string.

EntityBrowseView

The default view container component for most entities browse view. This is typically responsible for rendering one or more grid sections, but is capable of rendering any section configured in the metadata.

EntityGrid

The view-type usually used for rendering the list view for an entity domain.

EntityView

The primary view component for rendering the create or edit form for managing the data for an entity.

ExportMaintenance

The default view container component for rendering the export section tab.

Header

The component rendered in BaseLayout at the top of the screen, which usually contains buttons or dropdown menus pertaining to user and application settings.

ImportMaintenance

The default view container component for rendering the import screen. This is typically responsible for rendering ImportsGrid.

ImportsGrid

The view-type usually used for rendering the list of the import processes.

MyChanges

This is a view for rendering the list grids dealing with a user’s sandbox changes. It manages which grid is rendered based on the view parameter of the location search string.

Navigation

The component that renders the application selector and navigation menu for the application.

OrderView

View component that renders the Order details screen. This component provides a consolidated view of an order and its relationships.

SimpleForm

A view-type component used for simply rendering a set of form components. This is typically used as a replacement for ENTITY for simpler form submission use cases.

useNavigationCache

A hook that reads from and saves to the navigation cache data stored in the browser.

ViewTypeRenderer

This component renders metadata-driven view components of classifier "View". Read more about all types of renderable view components in the View Metadata exports table.