Integration

About Content Picker integration

This page describes how to load the Content Picker JavaScript in an embedding application and how to open the picker with CsMediaLibrary.create.

Load the code

The JavaScript needs to be loaded, usually directly from the corresponding HTML file. The standard build contains index.html with everything necessary, but this file is only an example.

The most common and recommended way to load JavaScript is the standard script element:

<script type="text/javascript" src="app.min.js"></script>

You can also load the file from a relative or an absolute URL:

<script type="text/javascript" src="https://<domain>/content-picker/app.min.js"></script>

The JavaScript file registers the global variable CsMediaLibrary of the type ICsMediaLibrary. For the type definition, see the attached file CsMediaLibrary.tsx.

The sample index.html loads its configuration from the relative URL picker-config.json and passes it to CsMediaLibrary.create. Content Picker itself does not request this file. In the sample index.html, a button registered dynamically in the DOM opens the picker with its onclick event, and the sample callback shows the returned JSON to the user.

Execute the picker

To initialize and show the picker, invoke the method named create on the global variable CsMediaLibrary. It takes one argument: an object with several properties, which are defined in the TypeScript sources. The most important ones are:

• apiUrl: Base URL of HCMS, ending with the API version, for example /hcms/v2.0.

• cancel: Callback invoked when the picker is closed by the Cancel button (a function with no argument).

• success: Callback invoked when the picker is closed by the Import button (function with an array of objects as an argument). Each object in the array is the value of the selected entity (usually picker_image).

All other properties are optional. The following are the most commonly used:

• language: The language to use. Supported languages are en, de, fr, it, and es. For details, see "Language selection" below.

• themeName: Predefined theme, censhare (default) or marmind. For details, see "Themes" below.

• themeUrl: URL of the theme stylesheet.

• theme: Overrides for colors, font, and logo.

• middlewareUrl: Optional URL (relative or absolute) of the HCMS Client for compatible configuration, for example for theming. In the Docker image, the environment variable MIDDLEWARE_URL sets it.

Example

CsMediaLibrary.create({
  apiUrl: '/hcms/v2.0',
  language: 'en',
  cancel: () => {},
  success: (selected) => {
    console.log(selected);
  }
});

Language selection

When "CsMediaLibrary.create()" opens the picker, Content Picker selects the language in this order:

1. The language value of the integration, if Content Picker supports it.

2. Otherwise, the first supported language from the preferred languages of the browser (navigator.languages).

3. Otherwise, English.

An unsupported value does not force English. Content Picker continues with the preferred languages of the browser. Before Content Picker 2.0.0, Content Picker always started in English. To keep this behavior, pass "language: 'en'" explicitly.

Region and script parts are ignored. For example, de-DE, DE, and de_DE select German.

Content Picker selects the language once, when "create()" is called. You cannot switch the language while the picker is open. Calling "create()" again replaces the running picker.

Page JavaScript cannot read the HTTP header Accept-Language. Therefore, Content Picker uses navigator.languages. Safari provides only the first browser language, so Content Picker does not use a second preference there.

To find out which language Content Picker uses without opening it, call "CsMediaLibrary.resolveLocale()". The method accepts one optional value or a list of values.

For the language behavior in Marmind and for labels that the Censhare Server supplies, see Content Picker.

Themes

• themeName: Predefined theme, censhare (default) or marmind. Theme names are not case-sensitive. An unknown name logs a warning, and Content Picker uses censhare.

• themeUrl: URL of the theme stylesheet. It replaces the default location "themes/<name>.css". Content Picker uses it even when the selected theme is censhare.

• theme: Overrides for colors, font, and logo. Content Picker deep-merges them onto the selected theme.

Every theme except censhare loads "themes/<name>.css" from the directory of app.min.js. Deploy the complete build directory, including the themes/ directory.

Content Picker waits up to 2 seconds for the theme stylesheet. If the stylesheet fails or loads slowly, Content Picker opens anyway. It keeps the colors, font, and logo of the selected theme, but uses the Censhare sizes and borders.

Examples are available in the Content Picker repository. deploy/marmind/index.html shows the Marmind theme and the parameter "?theme=". web/index.html shows the parameter "?theme=marmind".