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

OpenCms ships with a demo website. It is meant to demonstrate OpenCms features, has a special focus on new features and takes a "what is possible" approach to show things. The demo has mainly two purposes:

  • It is a very rich source of information on how to use OpenCms.
  • It can be reused and adjusted to set up your own website.

For the first purpose, the complexity of the examples is somewhat hindering. Therefore, we provide some background information here.

For the second purpose, the demo, in particular the underlying template, is perfectly suitable if you want to base your website on Bootstrap. The demo is built with the Apollo template. The template is basically a set of (layout) elements that allow to build Bootstrap grid layouts like in a modular construction system. Additionally, the Apollo template features a variety of contents and formatters, together being a feature-rich tool-kit to build up your own website.

The interesting thing to understand is not the demo content itself, it's the underlying Apollo template. We will provide some basic information on the design of the template. The Apollo template is available stand-alone at GitHub. When you got the basic information here, you may have a look there to get detailed information.

What belongs to the Apollo template?

The template consists of several modules. All of them are named org.opencms.apollo.xxx. There are two modules you need to install to use the template:

  • org.opencms.apollo.theme: contains the default Apollo CSS, JavaScript and resources
  • org.opencms.apollo.template.core: contains the main template and essential resource types

All other modules are kind of "add-ons" that add extra resource types and suitable formatters. Here you can choose the "add-ons" you want.

An exception is the module org.opencms.apollo.template.democontents. It just contains the contents of the demo shipped with OpenCms.

The Apollo template - a bootstrap wrapper

The Apollo template is a bootstrap wrapper. The intention is to:

  • Start with an empty page (the template exposes only one big container for the body)
  • Add (usually various and nested) layout rows with different columns to set up the "rough" design of a page.
  • Add content into cols of layout rows. This can be done by element authors (if not configured differently).

Containers exposed by layout rows can be restricted, such that only template developers can add contents, or also content editors.

The bootstrap grid system

Bootstrap is a framework for responsive web design. The heart of bootstrap is a grid system. A bootstrap page consists of a series of rows that contain columns. Each row is by default divided into 12 equally wide parts and a column can span over 1 to 12 of these parts. Each colum itself can include a row again.

The responsive part is: Bootstrap distinguishes four devices by screen width. And the width of columns can be given for each of these devices.

Device type Extra small devices (phones) Small devices (tablets) Medium devices (Desktops) Large devices (Desktops)
Screen size <768px 768px-991px 992px-1199px >= 1200px

Building a page with the Apollo template

Building a bootstrap page with the demo contents, works like using a construction kit. You just have to combine building blocks.

The template has just one container, where you can place various layout layers inside.

For example, if you want a design with header, body and footer, you may place three template rows in page container that is exposed by the template.Note that in the current demo, the complete head and foot areas are implemented as model groups.

The exposed containers for the different areas have different permission restrictions: header and footer can only be filled by template developers.

Having the above basic layout, you can move onto adding layout rows. A next useful step is to add a container for the page body. To ease drag & drop the demo contents provide two different layout levels: grid and row. They are, in terms of Bootstrap, the same, but they are configured such that the row level elements fit into the grid level elements, while content elements only fit into row elements by default.

Below, you see a section (container) for rows added to page body. So we do not use the grid level elements. It is simply not necessary for simple pages.

Now we can add rows to the segment. The demo has several different predefined rows. We add two here.

Note that in the above figure, one of the edit points is darker than the others. It's actually not one edit point. It are two overlapping edit points. The one for the segment and the one for the upper row. To get access to both of them you can iterate the different nesting levels of the containers via the short cut CTRL + SHIFT + e.

The final step after having all the layout set up is to add contents. Contents fit in all containers for "Element" - the blue ones above.

Details about the layout rows

As seen in the section above, the layout rows are the essential building block for the page layout. Have a look at them. Explore the rows from the demo.

The layout rows are very flexible. In the content itself you store:

  • Title: The title of the row as displayed in the "Add wizard"
  • PreMarkup/PostMarkup: The HTML that is rendered around the containers exposed by the row. You can use macros $(param) and $(link). They are replaced with the corresponding element settings, where link is processed by the link substitution. Use $(param) for example to allow for adding CSS classes.
  • Container: The type of the containers into which the row should fit.
  • Column: Settings for the columns the row renders.
  • Defaults: Common settings that are used for all configured columns (if the value is not explicitly set for the respective column)

Additionally to the options in the content itself, rows have various element settings:

  • Param: Value for the $(param) macro in pre and post markup.
  • Link: A valid link as substituion for the $(link) macro in pre and post markup.
  • Container: Overwrite the container type for the rendered containers/columns (can be a comma-separated list of container types)
  • Detail page settings: Select, if a container should be marked as detail container or if the whole row is shown only on detail pages.

Typical way to work with the template

The way to build your webpage is typically as follows:

  • The template developers provide template pages that have built up the page structure to the extent that all containers where only template developers can add content are already filled
  • Editors can add layout rows and content (where it is allowed)
  • Element authors can add content (where it is allowed)

Technically interesting spots

The demo is a good source of information for many features of OpenCms. Here we pick only some of them.

The element views

Building up a page with the Apollo template involves two different steps:

  • The layout via layout rows
  • Adding content

Each task has its own element view: The "Template" view for layout rows and the "Content elements" view for adding content. By using two element views, we get a clearer separation of concerns and also (partly) omits overlapping edit points. The "Content elements" view is a view from the OpenCms core. The "Templates" view is added by the Apollo template. It is located under /system/modules/org.opencms.apollo.template.core/elementviews/. Since it is of type elementview, it is automatically considered as element view by the system, i.e., it appears in all dialogs where element views can be chosen. The name used for the view is set by editing the view content. See here for details.

The interesting part are the permissions: Element views are only visible to users that have view and read permissions on the element view content. In the demo, the "Template" element view is only visible to editors. This is achieved by setting the permissions on the element view's content accordingly:

  • Overwrite inherited permissions
  • Add only view and read permissions for the role editor

The following figure shows the permissions for the view

Example for user generated content

In the demo, blog entries can be added via a form in the online project. Also existing entries can be edited via that form - but only by logged in users. General information on user generated content are found here. In this section we only point you to the resources interesting for the example:

  • The form is found under "Apollo Demo" -> "Blog" -> "Post a new blog entry"
  • You are also directed to the form if you click "Edit this blog entry" in the detail view of a blog.
  • The form is rendered via a formatter of the UGC configuration content
    • The formatter is found under /system/modules/org.opencms.apollo/formatters/blog_ugc-form.jsp
    • The formatter configuration under: /system/modules/org.opencms.apollo/formatters/blog_ugc-form.xml
  • The JavaScript for the UGC connection: /system/modules/org.opencms.apollo/resources/js/ugc/ugc-blog.js

The resources used for the form are all part of the module org.opencms.apollo.template.blog.

Macro formatters

Macro formatters are used extensivly in the Apollo demo. They come with the org.opencms.apollo.template.democontents module and are located under /sites/default/.formatters/.

Reuse groups

The demo uses reuse groups for header and footer. The groups can be viewed and edited via the sitemap editor's "Templates" view.

Searching with <cms:search>

The demo's search page is implemented with the <cms:search> tag. The interesting spots are:

  • The search form content, that you can edit directly at the search page
  • The formatter for the search form content, found at /system/modules/org.opencms.apollo/formatters/jsp-search-formatter.jsp

Furthermore, the lists in the demo (for blog entries and events) use <cms:search>. Have a look at:

  • The list contents itself at the demo pages (and the exposed options)
  • The list formatters are part of the module org.opencms.apollo.list and found at /system/modules/org.opencms.apollo/formatters/list-xxx.jsp.

Image drag & drop

Images in the demo can be replaced via drag & drop. Just try to choose an image from the gallery and drop it at the page. Image drag & drop is enabled in the formatters that render the image, e.g., have a look at /system/modules/org.opencms.apollo/formatters/image-enlarge.jsp.

Using the Apollo template for your own website

The Apollo template, without the demo contents, is a good starting point for your own website. But, not using any demo content you must define your own macro formatters and also rebuild the basic layout rows that are already present in the demo content. So you should think about copying these for your website and then start building model groups and template pages.

Moreover, it is likely that you want to adjust the styling for your website. The Apollo template uses Sass and Grunt to generate one minified CSS file that is included directly in the template JSP and additional theme CSS files that are used to adjust the default style. Additionally Grunt is used to create one big Java Script file, also included in the template and also to handle additional resources, e.g. images.

The suggestion to adjust styles is to write your own theme CSS file and manipulate the Grunt file to build your theme CSS as well. The theme can be selected via the property "Apollo Theme CSS" (apollo.theme).

To add your own styles, checkout the repository of the Apollo template from GitHub. The respository contains a Gruntfile.js at top-level and a folder apollo-src with all CSS, Java Script and additional resources. The subfolders contain again Grunt files. To add your theme, you can add it like the ones under apollo-src/scss-themes/. The simplest way is to put your theme in the same folder and add it to the Gruntparts.js in that folder. If you like to keep your adjustments in an own project, you need to set up suitable Grunt files for your project that are based on the ones of the Apollo template.

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.