1. External

Configure the external component

Before you upload your JavaScript bundle, ensure the interface includes the following functions:

  • render, which runs when the component is rendered and receives one object as a parameter with data and interaction options.
  • unmount, which runs when the component is unmounted.
Note

External components have access to a pre-authenticated Content Hub JavaScript SDK client for sending HTTP requests to Sitecore Content Hub. The SDK provides dedicated clients for common operations, and a raw client for custom requests. For requests to third-party servers, you can use standard browser APIs such as Fetch.

Initialize

The createExternalRoot function receives the HTMLElement (container parameter) and can be used to mount code. To initialize the External component, put the following initialization logic inside the root of the component, outside the render function:

export default function createExternalRoot(rootElement) {
    console.log("Initializing component");

    return {
        render(props) {
            console.log("Rendering component");

            rootElement.innerHTML = "Hello world";
        },
        unmount() {
            rootElement.innerHTML = "";
        },
    };
}

Render

The render function renders the contents of the External component inside a div in Content Hub and mounts the UI of the external component to the Document Object Model (DOM). This function receives an object containing the following data:

  • name - string.

  • theme - material user interface theme object providing styling properties, such as fonts and colors.

  • client - due to issues with the pre-authenticated JavaScript SDK client's capability to serialize and deserialize complex JSON, we recommend you create your own client instance when using the Querying client. To access the client include npm: @sitecore/sc-contenthub-webclient-sdk in your bundle and use the second argument that is passed to createExternalRoot to create an authenticated client instance. The new signature of createExternalRoot is:

    createExternalRoot(
  container: HTMLElement,
  clientBuilder: (constructor: typeof ContentHubClient) => IExtendedContentHubClient
)
    Note

    Please note that not all clients can be instantiated correctly. An example is the entityFactory client. To use this client, do the following:

    await client.entityFactory.createAsync("definitionName");

  • config - optional configuration passed to the external component (defaults to an empty object).

  • api - read-only value (ExternalApi).

  • entity - entity | null.

  • user - read-only value (ExternalUser) with the structure as described in the next section.

  • options - object with the structure as described in the next section.

  • icon - an object with a method to add Content Hub icons to and HTML element.

Important

Do not pass the theme directly to the customer's Material UI components. The Material UI version might differ from the one used in Content Hub and, therefore, might not be fully compatible. Instead, use CSS variables for styling.

Get smaller bundle sizes

To get smaller bundle sizes when including the JS SDK in your external component bundle, instantiate the desired subclients using the authenticated client returned by the clientBuilder. For example, this approach prevents bundlers from identifying and eliminating unreachable code:

const client = clientBuilder (ContentHubClient);
// Cannot be tree-shaken.
await client.querying.queryAsync(...);

To inform bundlers that you only need a specific part of the client, such as the queryClient in the following example, do the following:

const queryClient = new QueryingClient (clientBuilder ());
// Can be tree-shaken.
await queryClient.queryAsync(...);

Calling clientBuilder without arguments returns the authenticated instance that is already used by the application.

Structure of the user object

The user object has the following data.

export interface ExternalUser {
    id: number;
    userName: string;
    userGroups: Array<string>;
    privileges: Array<string>;
    identifier: string;
    userAvatar?: string;
}
Structure of the options object

The options object has the following data.

/**
       * Id of the entity in the current context.
       */
      entityId?: number;

      /**
       * Culture in the current context.
       */
      culture?: CultureInfo;

      /**
       * Indicates if the page is wrapped in a modal.
       */
      isInModal?: boolean;

      /**
       * Indicates if editing is active in the current context.
       *
       */
      isEditing?: boolean;

      /**
       * The editing mode for the current context.
       *
       * "readonly" | "edit" | "inherit"
       *
       * @defaultValue `"inherit"`
       */
      editingMode?: EditingMode;

      /**
       * Indicates if the component is currently rendered inside a sidebar.
       */
      isInSidebar?: boolean;

      /**
       * Indicates if the component is currently rendered inside a tabs component.
       */
      isInTab?: boolean;

Entity property

The entity property is passed on the same level as the config and the theme objects. It consists of the following information:

systemProperties: SystemProperties;
properties: Record<string, Record<CultureInfo, unknown>>;
relations: Record<string, Array<number>>;
permissions: Record<string, Optional<boolean>>;
renditions: Record<string, Array<string | URI>>;
setPropertyValue("M.Localization.Entry.Template", "some value", "en-US");
setRelatedIds("AssetMediaToAsset", [45], 0)

Available objects and methods include:

systemProperties

This object holds the system properties for the current entity.

{
  createdBy: 6,
  id: 120,
  identifier: "kadu7AeZQym6hlFnp_mP8A",
  ...
}

properties

This object holds the properties for the current entity.

{
 Title: {
  Invariant: "title"
 },
 FileName: {
  Invariant: "file name"
 },
 Description: {
  "en-US" : "English description",
  "nl-BE" : "Dutch description"
 }
 ...
}

relations

This object holds the properties for the current entity.

{
  AssetMediaToAsset: [1029],
  AssetToAssetSelfRelation_0: [],
  AssetToAssetSelfRelation_1: [33322],
  MasterFile: [35687],
  ...
}

permissions

This object holds the permissions for the current entity.

{
  addtocollection: true,
  addversion: true,
  approve: true,
  archive: true,
  ...
}

renditions

This object holds the renditions for the current entity.

{
  bigthumbnail: ['https://localhost:5009/api/delivery/local-62f30fcc…id=6&rendition=bigthumbnail&signature=tpUrpTdJwxE']
  created_by: ['https://localhost:5009/api/delivery/local-d25e003a…d=35781&rendition=thumbnail&signature=yDa_TROvvnw']
  downloadAlternative: ['https://localhost:5009/api/delivery/local-6e770863…ndition=downloadAlternative&signature=OoDGgd7aMw8']
  downloadOriginal: ['https://localhost:5009/api/delivery/local-6e770863…&rendition=downloadOriginal&signature=V-BQoLc6jTI']
  downloadPreview: ['https://localhost:5009/api/delivery/local-01d326bd…6&rendition=downloadPreview&signature=aXPZQVw1kBE']
  ...
}

setPropertyValue

This is a method to change or set the value of an entity's property. It receives the name of the property, the value, and an optional culture.

setPropertyValue("M.Localization.Entry.Template", "some value", "en-US");

IconComponent

This is a method to load SVG icons used by Content Hub. An icon is an object passed to the main object received by the render function. This object has a method called insertContentHubIconInElement, which requires an icon name and an HTMLElement to render the icon.

icon: { insertContentHubIconInElement: (icon: string, htmlElement: HTMLElement) => Promise<void> };

setRelatedIds

This is a method to change or set the value of an entity's relation. It receives the relation name, the array of entityIds, and an optional relation role.

setRelatedIds("AssetMediaToAsset", [45], 0)

The relation role that can be passed to the setRelatedIds method is a number.

Parent = 0,
Child = 1
Important

When the External component is not used on a details page, the entity is null. In custom code make sure the property exists and is not null.

API object

The api object holds methods to interact with the Search, Selection, and Details components and to display notifications:

api:{
    search: {
      updateQuery: (searchIdentifier: string, query: string) => void;
      addFilters: (searchIdentifier: string, filters: Array<FieldFilterRequestResource>) => void;
      updateFullTextFilter: (searchIdentifier: string, text: string) => void;
      clearFullTextFilter: (searchIdentifier: string) => void;
      clearAllFilters: (searchIdentifier: string) => void;
      getEventSearchIdentifier: (searchIdentifier: string) => string;
    },
    notifier: {
      notifySuccess: (message: string) => void;
      notifyError: (message: string) => void;
      notifyWarning: (message: string) => void;
      notifyInfo: (message: string) => void;
    },
    selection: {
     addToSelection: (ids: Array<number>, selectionPoolIdentifier: string, subPoolId?: number) => void;
     removeFromSelection: (ids: Array<number>, selectionPoolIdentifier: string, subPoolId?: number) => void;
     clearSelection: (selectionPoolIdentifier: string, subPoolId?: number, definitionNames?: Array<string>) => void;
    },
    details: {
      setEntitySource: (identifier: string, entityId: number) => void
    }
  }

The following methods let you add or remove filters:

  • updateQuery: (searchIdentifier: string, query: string) => void; - receives the Search component identifier and the new query as parameters; triggers a new search request with an updated query.
  • addFilters: (searchIdentifier: string, filters: Array FieldFilterRequestResource>) => void; - receives as parameters the Search component identifier and an array of filters to set; triggers a new search request with the updated filters.
  • clearAllFilters: (searchIdentifier: string) => void; - clears all filters, including any visual search filters added through an external Search component.
  • updateFullTextFilter: (searchIdentifier: string, text: string) => void; - receives the Search component identifier and a new text value as parameters; triggers a new search request with the updated full-text filter.
  • clearFullTextFilter: (searchIdentifier: string) => void; - receives the Search component identifier as parameter; triggers a new search request with an empty full-text filter.
  • getEventSearchIdentifier: (searchIdentifier: string) => string; - receives the Search component identifier as parameter; returns the identifier to check when subscribed to the SEARCH_FINISHED event.
  • activate(searchIdentifier: string): void - activates the Search component with the specified identifier and begins to send search requests.
  • addListener: (searchIdentifier: string, eventName: SearchEvent, listener: SearchEventListener) => DisposeSearchEventListener - allows external users to add a listener that executes when the event it is listening to occurs. The only event currently available is BEFORE_SEARCH. The listeners for this event receive a payload object in the form { searchRequest: SearchRequest } and the code inside the listener modifies this SearchRequest. When false is returned by any listener, the search request will be canceled. The addListener method returns a dispose function that users can call when needed. This dispose method, when called, removes the listener that was added.
Note

Examples on how to implement external page components are available to get you started.

If you have suggestions for improving this article, let us know!