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

For examples on how to write and build a JavaScript ECMAScript module as an external component for Sitecore Content Hub, see the Sitecore.CH.ExternalComponents.Examples repository . Examples on how to implement external page components are available to get you started.

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:

RequestResponse

 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. You can see how to do this in the examples provided in the Sitecore.CH.ExternalComponents.Examples repository. 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:

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

    For sample code that creates a client, see Example to create client.

  • 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.

Entity property

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

RequestResponse

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.

RequestResponse

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

properties

This object holds the properties for the current entity.

RequestResponse

{
 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.

RequestResponse

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

permissions

This object holds the permissions for the current entity.

RequestResponse

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

renditions

This object holds the renditions for the current entity.

RequestResponse

{
  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.

RequestResponse

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.

RequestResponse

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.

RequestResponse

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

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

RequestResponse

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:

RequestResponse

```json
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;
      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:

Do you have some feedback for us?

If you have suggestions for improving this article,