configureContentBrowser(options)

Sets global options for the Content Browser.

You can optionally customize several aspects of the Content Browser. This includes the search filters shown on the left side (filters) as well as a common baseFilter to be additionally applied to each of the filters.

A configuration example with a base filter and one general filter definition:

An example of a configuration with a filters definition which conditionally changes at runtime.

Options

  • baseFilter – An object with a single property, query (an ObjSearch)
  • filters – Either an object (filter definition) or a function returning a filter definition for the context (executed when the Content Browser is opened).

Filter definition

The filter definition basically includes labeled search filter rules. There are three types of filters:

  • tree filters (type: 'tree'- default)
  • radio button filters (type: 'radioButton')
  • checkbox filters (type: 'checkbox')

The tree filter lets you arrange the filter nodes hierarchically (using the filter item property options for nested filter items) and thus group them logically. This allows you to concisely present even a fairly complicated filter set.

The radio button and checkbox filters allow you to present filter options as either radio buttons or checkboxes, giving the user the possibility to further restrict the results obtained by the selected (tree) filter. With checkboxes, an editor may select multiple items while with radio buttons only a single item can be selected at a time. Unlike the tree filter, these filters cannot be organized hierarchically.

In addition to these filter types, there are several options for defining how the filters are presented to the user when the Content Browser is opened for the first time:

  • title (String) – A short description of the filter.
  • expanded (boolean) – The children of a filter are initially visible.
  • selected (boolean) – Preselects a filter item.
  • icon (String) – An icon representing the filtered objects. The available icons are shown in the list below.
    [New in 1.33.0] The icon can also be imported, e.g. from the “assets/images” directory, or referenced by an image URL. It should preferably be an SVG file. Note that Scrivito will adapt the image colors to match the Scrivito UI.
View the list of predefined icons

The constraints a filter should impose can be specified using the field, operator and value keys (FOV). They are equivalent to the arguments accepted by Obj.where. With hierarchical filters, field and operator may be specified on a parent filter level.

A simple configuration for defining a single filter item that finds all images looks like this (restrictByObjClass is the filter’s freely chosen name):

Note that equals is the default operator and therefore could have been omitted in the example above.

If the FOV options are not powerful enough for a particular purpose, you can use the query option which offers the full power of the Obj.where API. Simply specify the chainable search object in the filter configuration.

A filter definition that makes use of a query option for finding all images might look like this:

Whenever possible, the declarative FOV options should be preferred over the programmatical query parameter, because they are more flexible regarding uploads and presets, for example.

Here is an example of a hierarchical filter for selecting images by their content type.

Context-aware filter definition

A context-aware filter definition is a function that receives one argument and returns a filter definition.

The only argument of the function is context. The context specifies the restrictions to apply when the Content Browser is used for selecting a CMS object. context is an object with the following key:

  • _validObjClasses – either undefined or an Array of object class names. If undefined, an object of any class can be selected. If an array of names is specified, only objects of the given class(es) are made available for selection. This corresponds to the value of the only option of an attribute of the reference or referencelist type if the Content Browser is used to set the value of such an attribute.

Here’s an example of a dynamic filter definition which returns a reduced filter definition if an image is to be selected: