The concept of developing templates for OpenCms 8

OpenCms 8.5.1 got released last week and while test-driving the new edition I thought why not share a little knowledge about how to develop templates for OpenCms 8.x. The concept how it is done (and therefore the way to develop) changed rather significantly and this had been an impediment for days in our last project until we tackled it. This blog post aims to help you understand that new concept.

I want to give you two examples, one for version 7 and one for version 8. Both will have editable areas and the OpenCms 8 example will make use of so called “formatters” and inline editing, both being new state of the art features that were not available previously. These should make the life of content editors easier but developing got more complex, naturally.

I assume you are familiar with the general OpenCms terms, such as module, system-folder, site, template, workplace, structured content and you already know how to set up an initial instance of OpenCms.

For years I’ve been creating JSPs in a module’s template folder, and editors could create a new “Page with free text” and select the template.

That’s it. Sure, a template could include more elements and rely on multiple structured contents, but that is not a necessity. If you wanted to have a simple template with an editable area this code would have been enough for a start:
<%@ taglib prefix=“cms“ uri=“http://www.opencms.org/taglib/cms“ %>

Basic oldskewl OpenCms Template

Now let’s talk about OpenCms 8 template development. To understand why we need to create certain resources I’d like to start from an editor’s point of view: create a new page in a site.

In OpenCms 8 editors should work with the sitemap editor and simply drag and drop a new page into an existing site. For that to work we have to tell the Cms what model pages (~ the “new” templates) are available using the sitemap configuration located in /.content/.config of a site. Technically the drag and drop process copies an existing resource (the model page) to the destination (the index.html somewhere in the content).

Model pages are based on container page templates that reside in the module just like the old templates used to. Now, that’s one more step, why not link to the container page templates directly? Well, model pages *can* have pre-defined containers, the container page template is just the wireframe for containers.

Containers are elements that can be added to a page with the new drag and drop page editing of OpenCms 8. Containers are structured contents, so you need an XSD that defines the structured content and add module config that enlists all available resource types.

The XSD also defines a naming scheme where OpenCms should store the corresponding contents.

Finally the XSD defines a set of formatters. Depending on where you drag your content different representations can be chosen.

With this construct we accomplished the same as with OpenCms 7, but we can make use of OpenCms 8 features such as drag and drop, inline-editing and formatters.

From a developer’s point of view the new concept is far more demanding than previous ones. I hope the general reception will still be good, at least customers love the new features (my experience from the last project). Developing for OpenCms 8 is more difficult and more complex and not as intuitive as it used to be – developers will have to adjust to that, but your clients will be grateful for sure.

Attached you will find a module that contains both the simple template and the feature rich OpenCms8 container page (also with inline editing enabled) as well as content you can import in a test site. It should be easy to reverse engineer this little basic example, I hope it will help you get started developing templates for OpenCms 8. Happy coding! 🙂

The module: de.codecentric.opencms8.demo_1.1.zip
The content (please import into a new/blank site, otherwise this may overwrite existing sitemap configs): content.zip