Content Browser Overview

Content Browser Overview

The Content Browser is the central component for editors to add, update, and delete CMS content represented by individual CMS objects. Images, videos, PDF files, web pages of any kind, but also contacts, locations, or papers can be handled by means of the Content Browser. Widgets cannot because they are page components, no individual CMS objects.

You can open the Content Browser when editing CMS attributes of the link, linklist, reference, and referencelist types. The JavaScript in-place editors for these attribute types already use the Content Browser. You can always look at their implementation to get a better understanding of how to use the Content Browser from within your own code.

The Content Browser is a gem Scrivito Editors adds to your application. It is completely based on the Scrivito JavaScript API.

The Content Browser configuration can be found in the app/assets/javascripts directory of your application, e.g. in the content_browser_filters.js file.

Tag support

The Content Browser supports tags for further narrowing down the CMS objects listed (as a result of a search, for example). If, for example, you use tags as a means to categorize images by their prevailing colors, you can select the desired color combination to find the matching images.

A CMS object matches a tag-based search if at least all of the selected tags have been assigned to it.

To utilize tag filtering in the Content Browser, add a stringlist attribute named “tags” to those CMS object classes you want to support tagging:

To make the tags of a CMS object editable, render the “tags” attribute in the details view of the object class using the standard helper:

Display options

The titles of items shown in the content browser can be configured by means of description_for_editor. See Using Object Classes for an example.

The column on the right hand side contains the details view of the currently previewed item. See Page and Widget Views Explained for details about changing these views.

Filter options

For easily finding content (e.g. of a particular type), you can make filters available to the users. Three types of filters are available:

  • tree filters
  • radio_button filters
  • check_box filters

The tree filter lets you arrange the filter nodes hierarchically and thus group them logically. This allows you to concisely present even a fairly complicated filter set.

The radio button and check box filters allow you to present filter options as either radio or check_box buttons, giving the user the possibility to further restrict the results obtained by the selected filter. With check boxes, an editor may select multiple items while with radio buttons only a single item can be selected at a time. 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 first opened:

  • expanded – the children of a filter are initially visible
  • selected – preselects a filter item
  • icon – lets you specify one of the following 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 scrivito.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 (in CoffeeScript):

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 scrivito.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 FOV options should be preferred over the query parameter because they are more flexible regarding uploads and presets, for example.

A full FOV-style filter definition might look like this:

Contextual filters

A contextual filter lets you restrict the kind of CMS objects that can be selected using the Content Browser. If, for example, you want to make selecting videos for a video gallery easier for your users, you can have everything except videos hidden as the Content Browser is opened for a video or video gallery widget.

This can be done by implementing scrivito.content_browser.filters as a function that responds to the filter context passed to it. You can pass a filter context to this function simply by specifying it as a data-scrivito-editors-filter-context attribute when calling a helper such as scrivito_tag inside a view, or when opening the Content Browser using the scrivito.content_browser.open() JS API function (see the examples below).

Scrivito is already aware of image contexts, so you don't need to specify a data-scrivito-editors-filter-context attribute when calling scrivito_image_tag. To benefit from this awareness, simply provide a filter function that responds to the _image context, like so:

Please note that context names that start with an underscore are reserved for use by the Scrivito SDK.

Data attributes whose name starts with data-scrivito-editors-filter-context are picked up by the helpers included in the Scrivito editors gem and are passed on to the Content Browser. For example:

To pass a context to the scrivito.content_browser.open() JavaScript function, just set the filter_context option:

Upload options

Presetting attributes on upload

The Content Browser lets you specify attribute values that are automatically assigned to CMS objects created using the Content Browser, i.e. by means of uploading files. The preset configuration key can be specified for every selectable filter:

The definition above specifies that the language attribute of the CMS object created for an uploaded file is set to “en” if the user selected this filter prior to uploading the file. Analogously, it is set to “fr” if the corresponding filter was selected.

Note that selecting more than one value of a single-selection (enum) attribute is accepted when searching for content. However, when uploading content, this results in an error because the options are mutually exclusive. In this case, the user is asked to correct the selection and repeat the upload.

Default object classes for content types

When uploading content to the CMS by means of the Content Browser, a proper object class for the type of the uploaded content needs to be determined. For this, a mapping of default object classes and content types can be registered and queried.

For further details, please refer to the JavaScript API documentation.

Creation options

There are types of content that can neither be created in place nor uploaded, a collection of product data, for example, or a contact person. However, you can still create such content if you provide a filter for it and specify the enable_create option, like so:

This results in the following filters:

Note that the presets defined for a filter are not only applied when uploading files but also when creating content directly using the Content Browser. Most important, the _obj_class of the CMS objects to create needs to be specified as a preset.

If more than one filter has been selected and their presets are incompatible, the Create item button will be disabled. Click the disabled button to have the conflicting filters displayed in a dialog window.

You can explicitly set enable_create to false if you want users to create objects only by uploading files, or if the filter criteria are not suitable for new objects of a particular class.

Methods and callbacks

The Content Browser provides methods and callbacks you can use to interact with it or hook into the functionality and execute custom JavaScript code. Only one Content Browser instance can exist at a time.

Open the Content Browser:

Set a callback for saving:

Set a callback for closing without saving:

The Content Browser can be configured using the following options:

  • selection - enables preselecting a set of contents by passing an array of their ids.
  • selection_mode - may be either single or multi for selecting a single item or multiple items, respectively.
  • base_query - a chainable search object that is applied to each filter further limiting the results.
  • filters - override the global filter configuration, see the section on filters options.

Thumbnail tooltips

In the thumbnail view, a customizable tooltip is displayed for every CMS object. The default for non-binary and binary CMS objects uses their title and object class, or their file name and file size, respectively:

Tooltips are composed of a title (the upper part) and a subtitle (the lower part). The title is determined by executing the description_for_editor callback, while the subtitle results from calling info_for_content_browser. Both instance methods can be overridden for Obj and its subclasses, e.g. “BlogPost”:

Note that description_for_editor is part of the Scrivito SDK while info_for_content_browser is not. The latter is added subsequently to the BasicObj model by the ContentBrowser.