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:

Copy
Scrivito.configureContentBrowser({
  filters: {
   // filter definition
  },
  baseFilter: {
    query: Scrivito.Obj.where('site', 'equals', window.top.location.hostname)
  }
});

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

Copy
Scrivito.configureContentBrowser({
  filters: function(context) {
    return {
      // filter definition adjusted depending on given context
    };
  },
  baseFilter: {
    query: Scrivito.Obj.where('site', 'equals', window.top.location.hostname)
  }
});

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 – a short description of the filter
  • expanded – the children of a filter are initially visible
  • selected – preselects a filter item
  • icon – lets you specify one of the icons shown here.

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):

Copy
Scrivito.configureContentBrowser({
  filters: {
    restrictByObjClass: {
      field: '_objClass',
      operator: 'equals',
      options: {
        images: {
          value: 'Image'
        }
      }
    }
  }
});

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:

Copy
Scrivito.configureContentBrowser({
  filters: {
    restrictByObjClass: {
      options: {
        images: {
          query: Scrivito.Obj.where('_objClass', 'equals', 'Image')
        }
      }
    }
  }
});

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.

Copy
Scrivito.configureContentBrowser({
  filters: {
    restrictByObjClass: {
      options: {
        images: {
          icon: 'image',
          field: '_objClass',
          operator: 'equals',
          value: 'Image',
          options: {
            JPEG: {
              field: 'blob:contentType',
              operator: 'contains',
              value: 'jpeg',
            },
            PNG: {
              field: 'blob:contentType',
              operator: 'contains',
              value: 'png',
            },
            SVG: {
              field: 'blob:contentType',
              operator: 'contains',
              value: 'svg',
            },
          },
        },
        // ... more filter definitions for other obj classes
      },
    },
    // filters using a dimension other than obj class (e.g. _lastChanged)
    // may additionally be defined here
  },
});

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:

Copy
Scrivito.configureContentBrowser({
  filters: function(context) {
    if (context._validObjClasses) {
      var validObjClasses = context._validObjClasses;
      if (validObjClasses.length === 1 && validObjClasses[0] === 'Image') {
        return {
          images: {
            icon: 'image',
            field: '_objClass',
            operator: 'equals',
            value: 'Image',
            options: {
              JPEG: {
                field: 'blob:contentType',
                operator: 'contains',
                value: 'jpeg'
              },
              PNG: {
                field: 'blob:contentType',
                operator: 'contains',
                value: 'png'
              },
              SVG: {
                field: 'blob:contentType',
                operator: 'contains',
                value: 'svg'
              }
            }
          }
        };
      }
    }
    // ... optionally return a general filter definition here
  }),
});