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:
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.
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.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 is a bootstrap wrapper. The intention is to:
Containers exposed by layout rows can be restricted, such that only template developers can add contents, or also content editors.
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 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.
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:
$(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.
Additionally to the options in the content itself, rows have various element settings:
$(param)macro in pre and post markup.
$(link)macro in pre and post markup.
The way to build your webpage is typically as follows:
The demo is a good source of information for many features of OpenCms. Here we pick only some of them.
Building up a page with the Apollo template involves two different steps:
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:
The following figure shows the permissions for the view
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 resources used for the form are all part of the module
The demo's search page is implemented with the
<cms:search> tag. The interesting spots are:
Furthermore, the lists in the demo (for blog entries and events) use
<cms:search>. Have a look at:
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
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.