Broadleaf Microservices

Contexts

This document covers several of the core link: React Contexts used throughout the admin application. Knowing these contexts is often important when making changes within the admin.

CatalogContext

The CatalogContext is provided by the TrackingContextProvider and is used for managing the current global catalog selection within the tenant-level admin.

interface CatalogContext {
  /**
   * The set of all assigned catalogs for the current site.
   */
  assignedCatalogs: [string],

  /**
   * The ID of the currently chosen catalog.
   */
  currentCatalogId: string,

  /**
   * The default locale for the current catalog selection.
   */
  currentCatalogLocale: string,

  /**
   * The primary method used for hydrating assigned catalogs.
   */
  hydrateAssignedCatalogs: () => Promise<void>;

  /**
   * The primary method used by the catalog selector (or other components) for
   * setting the current catalog.
   */
  setCurrentCatalogById: (catalogId: string) => void;
}

ChangeContainerContext / ChangeContainerCallbackContext

The ChangeContainerContext and ChangeContainerCallbackContext is provided by the ChangeContainerProvider which is rendered by sandboxable views, and is used for managing the current set of change summaries associated with the sandboxable view.

interface ChangeContainerContext {
  // the current change container name
  containerName: string;
  // the current change container ID
  containerId: string;
  // the summaries for the current change container
  containerSummaries: [object];
  // whether or not polling is disabled
  disablePolling: boolean;
  // an error that occurred when trying to poll summaries
  errorPollingSummaries?: Error;
  // whether or not summaries are being "polled"
  isPollingSummaries: boolean;
  // the last time we updated summaries
  lastUpdatedSummaries?: number;
}

interface ChangeContainerCallbackContext {
  /**
   * Polls the change summaries and sets change container state
   * using the provided container name and ID.
   */
  pollChangeSummaries: () => Promise<void>;

  /**
   * Updates the state with the provided `containerName` and `containerId`.
   */
  setChangeContainer: (changeContainer: { containerName?: string; containerId?: string; }) => void;

  /**
   * Disables polling by the provider either by `#pollChangeSummaries` or by
   * the internal re-poll done in reaction to `SandboxOperationContext` changes.
   */
  setDisableSummaryPolling: (isDisabled: boolean) => void;
}

ComponentRouterContext

The ComponentRouterContext that provides the current set of metadata component routes:

type ComponentRouterContext = [{
  componentId?: string;
  componentName?: string;
  exact: boolean;
  path: string;
  scopes: [string];
}]

DevSettingsContext

The DevSettingsContext is used for managing state around the dev settings within the application that are only available during development mode:

interface DevSettingsContext {
  /**
   * If the application is currently in dev mode, allowing dev settings.
   */
  devMode: boolean;
  /**
   * This controls if the dev settings modal is open
   */
  showDevSettings: boolean;
  /**
   * Enables the 'View Metadata' action on metadata components.
   */
  showMetadata: boolean;
}

I18nContext

The I18nContext is used for managing the current and available locales for the admin application itself:

interface I18nContext {
  /**
   * The currently selected locale code.
   */
  currentLocale: string;
  /**
   * The set of allowed locales.
   *
   */
  allowedLocales: [string];
  /**
   * Sets the current locale to the provided locale code.
   * @param locale the new locale code
   */
  setCurrentLocale: (locale: string) => void;
}
Note

This locale influences the translations of the admin labels, but not the underlying data.

LocaleContext

The LocaleContext is used for providing the default locale and allowed locales for the data being managed within the admin:

interface LocaleContext {
  allowedLocales: [string];
  defaultLocale: string;
}

MetadataContext

Thee MetadataContext is used for providing and managing the metadata state for the current view:

interface MetadataContext {
   /**
   * Whether or not the current user is allowed to augment metadata. This is used
   * to visually hide or show the controls around augmentation.
   */
  canAugment: boolean;

  /**
   * Fetches new metadata for the view container from the metadata service.
   */
  hydrateMetadata: () => Promise<void>;

  /**
   * Whether or not the current user is augmenting metadata. This flag is used
   * to indicate whether to render the augmentation controls or the "Live" view.
   *
   */
  isAugmenting: boolean;

  /**
   * The metadata for the view container.
   */
  metadata: {
    classifier: string;
    type: string;
    [key: string]: unknown;
  };

  /**
   * Toggles `isAugmenting` to either true or false.
   * @param isAugmenting the new value of `isAugmenting`
   */
  toggleAugmenting: (isAugmenting?: boolean) => void;
}

SandboxContext

The SandboxContext is used for managing the sandbox state with the current active sandbox and available sandboxes:

interface SandboxContext {
  /**
   * The ID of the currently active sandbox. Most of the time this will be the
   * user's default sandbox, but it can be changed using `#setCurrentSandboxById`.
   */
  currentSandboxId: string;

  /**
   * The primary method used for hyrating user sandboxes. This is typically
   * useful for down-stream components to populate (i.e., hydrate) the set
   * of user sandboxes to ensure they are up to date.
   */
  hydrateUserSandboxes: () => Promise<void>;

  /**
   * The primary method used by a sandbox selector component to set the current
   * sandbox by ID. This will be implemented by the sandbox provider component
   * to update the `currentSandboxId` state with a new sandbox ID.
   *
   * It is important that only a sandbox within the `userSandboxes` array is
   * passed to this setter.
   */
  setCurrentSandboxById: (sandboxId: string) => void;

  /**
   * The set of all available sandboxes for the current user. This array of
   * sandboxes should be resolved AFTER a user has been authenticated for the
   * current site.
   */
  userSandboxes: [{ id: string; name: string; color: string;}]
}

SandboxOperationContext / SandboxOperationDispatchContext

The SandboxOperationContext and SandboxOperationDispatchContext are used for providing state executing sandbox operations within sandboxable views:

interface SandboxOperationContext {
  isCancelled: boolean;
  isOperationInProgress: boolean;
  operationType?: string;
  operationData?: any;
  operationError?: Error;
}

type SandboxOperationDispatchContext = (action: any) => void;

TenantContext

The TenantContext is used for providing the current tenant state with the tenant and application information:

type TenantContext = [
  {
    applicationById: { [id: string]: { id: string; name: string; }},
    applicationId: string;
    applicationIds: [string];
    isFetchApplicationsQueued: boolean;
    tenantById: { [id: string]: { id: string; name: string; }},
    tenantId: string;
  },
  (action: any) => void
]

ToastContainerContext

The ToastContainerContext is used for providing the toast state and actions to add or remove toasts:

interface Toast {
  autoClose: boolean;
  closeOnClick: boolean;
  content: any;
  id: string;
  isPaused: boolean;
  pauseOnHover: boolean;
  progressDuration: number;
  progress: number;
  showProgress: boolean;
  type: string;
}

interface ToastContainerContext {
  addToast: (content: any, options: any) => void;
  dispatch: (action: any) => void;
  pauseToast: (toastId: string) => void;
  playToast: (toastId: string) => void;
  removeToast: (toastId: string) => void;
  state: {
    toastsById: { [toastId: string]: Toast }
  };
  updateToast: (toastId: string) => void;
}

TranslateModeContext / TranslateModeDispatchContext

The TranslateModeContext and TranslateModeDispatchContext are used for providing and managing the current translate mode state:

interface TranslateModeContext {
  /**
   * Whether or not the translate mode is currently active. This affects whether
   * non-translatable fields are read-only, and whether or not saves persist to
   * a special translation endpoint.
   */
  isActive: boolean;

  /**
   * The currently active locale selection. This is set when translate mode is
   * enabled by a user interaction. This should be a valid locale code.
   */
  locale: string;
}

type TranslateModeDispatchContext = (action: any) => void;

UserAccessContext / UserAccessDispatchContext

The UserAccessContext and UserAccessDispatchContext are used for providing the user access with details on what the current user has access to do:

interface UserAccessContext {
  /**
   * User operation types by scope.
   */
  operationTypesByScope: { [scope: string]: [string]; },

  /**
   * Request state for fetching by scope.
   */
  requestsByScope: { [scope: string]: { error?: Error, isFetching: boolean; lastUpdated?: number; }}
}

type UserAccessDispatchContext = (action: any) => void;