Customizing Content Editor pickers

Written by The Jahia Team

Pickers are one of the selector types used in Content Editor. This topic describes how to customize the rendering of the existing pickers. If you want to create your own picker from scratch, you should refer to Creating custom selector types for Content Editor.

Content pickers enable you to create a weak reference to a content item of your choice. Content Editor provides the following pickers:

Category picker
Content folder picker
Editorial picker
Editorial link picker
Image picker
File picker
Folder picker
Page picker
Site picker
User picker
User group picker

Assigning a picker to a content property

In the definitions.cnd file, a weak reference property using a picker is defined as:

[qant:myContent] > jnt:content, jmix:editorialContent
 - myFilePicker (weakreference,picker) < jnt:file

This definition specifies that an editorial picker will fill the value for the myFilePicker property. You specify the picker configuration that you want to use by adding the type option, as shown here.

[qant:myContent] > jnt:content, jmix:editorialContent
 ...
 - myFilePicker (weakreference,picker[type='file']) < jnt:file
 ...

The type option defines which configuration to use for the property. The configuration name has to be present in the application registry to allow Content Editor to resolve it. You can find available configurations in the Picker.configs.js Content Editor file.

The configurations are added in the registry with the pickerConfiguration key, for example:

ceRegistry.add('pickerConfiguration', ‘editorialLink’,...)

The field containing a picker displays like this in Content Editor.

Editors click on the field to open the picker modal.

Setting content type restrictions on a picker

If you just need to restrict the content types that editors can select in the picker, you don't need to declare a new custom picker. You only need to declare the restriction in the definitions.cnd file. In the example below, the picker for the myLocationPicker property allows editors to only select qant:location.

 [qant:customPicker] > jnt:content, qamix:qaContent, jmix:editorialContent
 - myLocationPicker (weakreference,picker) < qant:location

Creating a custom picker selector type

You can create a custom picker selector type in Content Editor. The process for adding the custom selector type picker is similar to how you add other selector types.

To add a custom picker selector type to the registry, you need to add a new picker configuration to the registry. This configuration is automatically applied by the resolveSelectorType function in Content Editor.

export const resolveSelectorType = ({selectorType, selectorOptions, displayName, ...field}) => {
    let selector = registry.get('selectorType', selectorType);
    if (selector) {
        if (selector.resolver) {
            return selector.resolver(selectorOptions);
        }

        selector.key = selectorType;
        return selector;
    }

    if (selectorType) {
        console.warn(`No renderer component for ${selectorType} selectorType`);
    } else {
        console.error(`Field ${displayName} has no selectorType !`, {selectorOptions, displayName, ...field});
    }

    return registry.get('selectorType', 'Text');
};

The resolveSelectorType function has the following parameters.

selectorType
The type of the selector. The selectorType for each picker is Picker. The picker selector type has a resolver function so it will be called with the selectorOptions to define which picker configuration to use.
selectorOptions
An array of options to help resolve the selector type. To define which picker to use, you must add an object in selectorOptions that specifies the name of the picker configuration. The following object specifies that the resolveType function looks for the picker configuration of the file type.
```
{
    "name": "type",
    "value" : "file"
}
```
displayName
Name that displays in the console error message if the selector type does not exist.
field
Information about the field that displays in the console error message if the selector type does not exist.

Configuring the selector type

You can add a custom selector type to your Jahia instance.

To add a custom selector type:

Add a picker configuration to the registry.
Specify the configuration to use in either the definitions.cnd file or a JSON definition file.

To add a new configuration, you must add an entry for the pickerConfiguration type in the registry.

Selector options:

cmp (mandatory)
The component that displays in the form

The cmp object in details:

picker (mandatory)
The picker component to use for the custom picker

There are two available pickers that can be found in the registry: the ContentPicker and the MediaPicker. These pickers can be a custom component as well.

searchSelectorType (mandatory)
Restricts the search field to this type of node
listTypesTable (mandatory)
List of the nodes types to display in the picker modal table
selectableTypesTable (mandatory)
List of the types of the nodes that can be selected
treeConfigs (mandatory)
The configuration for the navigation tree on the left of the modal

The treeConfigs object in detail:

rootPath
The root path to start the navigation at
openableTypes (mandatory)
List of browsable node types in the left navigation panel
type (optional)
The title of the modal is Select a file if the value of type is equal to files. Otherwise, the title is Select a content.

Setting a custom picker selector type

Registering a custom picker

The following picker configuration adds a configuration for a picker which allows editors to select nodes of the 'qant:location' type in Content Editor.

window.jahia.uiExtender.registry.add('pickerConfiguration', 'location', {
            cmp: {
                picker: window.jahia.uiExtender.registry.get('selectorType', 'ContentPicker'),
                treeConfigs: [{
                    rootPath: site => `/sites/${site}`,
                    openableTypes: ['jnt:page', 'jnt:navMenuText', 'jnt:virtualsite', 'jnt:contentFolder', 'nt:folder', 'jmix:siteContent', 'jmix:browsableInEditorialPicker'],
                    selectableTypes: ['jnt:page', 'jnt:navMenuText', 'jnt:virtualsite', 'jnt:contentFolder', 'nt:folder', 'jmix:siteContent', 'jmix:browsableInEditorialPicker'],
                    type: 'location',
                }],
                searchSelectorType: 'qant:location',
                listTypesTable: ['qant:location'],
                selectableTypesTable: ['qant:location']
            }
        })

Configuring the selector type in the definitions.cnd file

The following definition specifies that the qant:customPicker nodes has the myLocationPicker property, which is a weakreference of a qant:location node.

[qant:customPicker] > jnt:content, qamix:qaContent, jmix:editorialContent
 - myLocationPicker (weakreference,picker[type='location']) < qant:location

By specifying picker[type='location'] in the definition, Content Editor will use the location configuration defined in the registry (registry.add('pickerConfiguration', 'location'...).

Configuring the selector type with a JSON override

Consider the following definition in the definitions.cnd file.

[qant:customPicker] > jnt:content, qamix:qaContent, jmix:editorialContent
 - myObject (weakreference) < qant:myObject

For example, you can add the qant_customPicker.json file to specify the picker configuration to use.

{
   "name":"qant:customPicker",
   "displayName":"Custom picker",
   "description":"",
   "dynamic":false,
   "fields":[
      {
         "name":"myObject",
         "selectorType": "Picker",
         "selectorOptions":[{
            "name": "type",
            "value" : "location"
         }]
      }
   ]
}

The previous JSON definition specifies that the myObject field will use the Picker selector type ("selectorType": "Picker") and specifies the type of the picker through the selector options. The selector option has to contain an object with the property "name": "type" and the value is the name of the configuration to use for the picker, which in this case is "location".