Customizing Content Editor pickers

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:

1. Add a picker configuration to the registry.
2. 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".