Search the documentation
 Show GitHub edit links  Hide GitHub edit links
In OpenCms since: 9.5 Documented since: 9.5 Latest revision for: 9.5 Valid for OpenCms: 10.5.3

Element views allow the grouping of (elements of) resource types for editing them in the page editor. If more than one (non-empty) element view is available, the user can choose the view and depending on that view, can add, edit and move elements of different resource types in a page.

Element views are in particular useful to

  • allow the editing of content in nested containers where edit points may overlap,
  • get a better overview of the available content elements by grouping them task-specifically
  • control access to elements of a specific type depending on roles, group memberships or user permissions.

Defining an element view

Element views are resources of type elementview. Typically element views are defined in modules that expose the resources types that should be shown in an element view. By convention, element views are stored in a subfolder elementviews/ of the module folder. When an element view content is defined, it automatically makes up an element view, selectable in all resource type configurations and (if non-empty and accessible to the current user) selectable in the page editor.

Creating element view content

To create a new element view:

  • Open the explorer view of the traditional workplace.
  • Choose in which module the element view should be defined and (create and) move to the subfolder elementviews/ of this module.
  • Choose the "New wizard" and select "Other options" -> "Element view".
  • Choose a filename (typically with suffix .xml) and edit the metadata.

Editing the element view content

The element view content stores mainly the name of the view used when the view is displayed in the page editor's context menu. Moreover you can alter the display order.

Fig. [elementview_content]: Element view content
Content fields of the element view content
Title

The title is mapped to the Title property and used as name of the view in the page editor, if no title key is given.

Title key

A key from a workplace message bundle to show a localized name of the element view in the page editor. Provide only the rare key, e.g., myelementview.title.

Display order

Non-negative integer value to specify the display order relative to other element views. Element views with smaller numbers are displayed earlier.

Setting permissions in the element view content

By setting permissions on the element view content, you can determine who is allowed to see the view. Only users with permissions on the elementview content get the view displayed for selection in the page editor.

Interesting details on element views

Which element views can I choose via the page editor?

Element views can be added by modules. Thus, many different element views may exist, but you may not want to show all of them to all users.

Thus, element views can only be selected via the page editor if:

  • The user has permissions to see the element view at all.
  • The view is non-empty for the current page, i.e., at least one resource type is configured to be in the view via the sitemap or module configurationAnd the user has the rights to see resources of this type.

How are element views identified?

Element views are identified via the structure id of the element view content. Thus, element views with equal names imported via different modules will not conflict. The default view plays a special role. It has no content and is identified via the null id.

Which element view is chosen by default?

Element views are sorted by their display order. From the views that can be chosen, i.e., the non-empty views where the user has sufficient permissions to access them, a view with the smallest display order is chosen as default. Typically, if not empty, the default view is chosen by default.

If a user once selects a view, this view is kept - at least as long as it can be chosen.

How can I get and set the element view automatically?

The current view is stored in the session cache, i.e., in CmsADESessionCache. The class provides the according getter and setter.

You can improve this page

Please contribute your suggestions or comments regarding this topic on our wiki. For support questions, please use the OpenCms mailing list or go for professional support.