OpenCms documentation
OpenCms documentation

Creating a template JSP

One of the most important aspects of building a website is the creation of the required templates. Sites generated by OpenCms are built by using one or more templates that define a uniform layout of the content presented. Following the steps described here, you should be able to get your JSP template up and running in a short time.

When realising a website project, one typically starts developing a template JSP by transforming a static HTML prototype, as provided by a design agency for example, into a template JSP. In this tutorial it is assumed that you have a prototype of your choice available. The prototype should contain at least one HTML document called index.html that links to static CSS, JavaScript, and image resources relatively to the index file. Please have your HTML prototype ready as a ZIP file.

The index.html file should be located in a folder named templates/ whilst the static resources should be located in a folder called resources/ like shown below:

templates/index.html
resources/css/site.css
resources/img/image1.png
resources/img/image2.png
resources/img/image3.png
resources/img/image4.png
resources/js/site.js

Functionality in OpenCms (except the core functionality) is packaged in modules. All the resources needed to build a website reside in one or more modules as well. In particular, also the template JSP is packaged in a module. So let's create one.

After logging into the workplace, open the modules app and click on the wand icon to open the "create new module dialog". In the "create new module dialog", you will be asked to enter a package name that must fulfill the Java package name conventions. Use my.template as package name if you follow this tutorial. Enter a nice name and a module description as well as a module number. Below the author information, you can choose which folders should be created automatically. Choose only the module folder and the folder "elements". Typically you would also create the subfolders "templates" and "resources", but they will come in when we import our HTML prototype in the next step.

Confirm by clicking "ok" and the module will be created. Open the explorer and navigate to /system/modules/my.template/ to check that all module folders are available.

If the HTML prototype is zipped and you have named the module you just created my.template, use the explorer to navigate to the folder /system/modules/my.template. Upload the ZIP file here with the ZIP-inflating option. Afterwards go to /system/modules/my.template/templates/ and rename the index.html file into main.jsp, then right click on main.jsp and choose the option: “Advanced” -> “Change type”, choose the "Configurations" group and select "Page template". Confirm the choosen resource type with "ok" which closes the dialog. Now click on the main.jsp. A new browser window should open that shows the prototype correctly.

At the main.jsp, set the (individual) properties by means of the properties dialog:

  • Title to a meaningful value, for the tutorial "My Template".The title will appear in a list when choosing the template.
  • template to /system/modules/my.template/resources/css/site.css. This will cause the style to be used for the HTML editor when editing content.

Open the main.jsp with the code editor (right-click the file and choose "Edit" from the context menu) and add the following lines to the beginning of the file:

<%@page buffer="none" session="false" trimDirectiveWhitespaces="true" %>
<%@ taglib prefix="cms" uri="http://www.opencms.org/taglib/cms" %>
<%@ taglib prefix="fmt" uri="http://java.sun.com/jsp/jstl/fmt" %>
<%@ taglib prefix="fn" uri="http://java.sun.com/jsp/jstl/functions" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>

Then search for all referenced resources (CSS, Javascript, images) and change the links by replacing the href and the src attribute values according to the following examples:

href="<cms:link>%(link.weak:/system/modules/my.template/resources/css/site.css)</cms:link>"
src="<cms:link>%(link.weak:/system/modules/my.template/resources/js/site.js)</cms:link>"

Using the <cms:link> tag in combination with the %(link.weak:) macro as shwon in the example above has the advantage that—if you once rename or move a static resource file—OpenCms will automatically adjust the link in the template JSP for you.

Step 4: Insert containers and enable the page editor

In order to activate the OpenCms page editor, the so called advanced direct editing features must be activated. Advanced direct editing means that all necessary tools to edit and manage content is available in-place together with the web page the content editor is currently editing.

Just add the tag <cms:enable-ade/> to the head section of your template JSP.

If the content editor now opens a page, a toolbar appears at the top of the page that allows to add new contents, publish changes, set bookmarks, manage image galleries, and much more.

The toolbar has a height of 52 pixels. It is recommended to add a margin of 52 pixels at the top of the page, in order to prevent the toolbar hiding the actual page content when in the editing mode as shown in the example below.

<html>
<head>
  <title><cms:info property="opencms.title"/></title>
  <cms:enable-ade/>
  <c:if test="${cms.isEditMode}">
    <style type="text/css">
main {
margin-top: 52px;
}
    </style>
  </c:if>
</head>
<body>
  <main></main>
</body>
</html>

Somewhere in the prototype, there might be sections with content that should be editable by the content editor. Remove the HTML of these sections and insert a <cms:container> tag instead. This will enable the content editor to place elements via drag-and-drop. For the main content part, you could define the <cms:container> the tag as follows:

<main>
  <cms:container name="centercontainer" type="center">
    <div>Add contents here.</div>
  </cms:container>
</main>

Make sure that the <div> inside the <cms:container> tag has a defined width and height. With the introduction of the <cms:container> tag, the template JSP now has OpenCms specific funktionality integrated. One cannot preview this specifics by just opening the main.jsp file in the browser. Instead, it it is necessary to use a so called container page using the template to see a preview. See the next step on how to create a container page.

If you want to set your template for an existing site or subsite, go to the sitemap editor, choose the "Resources" view and open the properties dialog by clicking on the burger menu of the main folder of the (sub-)site. Then, in the tab "Complete Properties", set the property template to your template by choosing it (via its name "My Template") from the drop-down list.

If you want to create a new site that uses your template, use the "Site Management" in the administration view. Choose "New site" and fill out the form, in particular "Title", "Folder name", "Server URL" and "Template". The remaining things can be empty. For "Template" enter template=/system/modules/my.template/templates/main.jsp. For "Server URL" you may choose "http://localhost:8081". If you created the site, go to the explorer view and switch to the newly created site. In this site's root folder add an index.html by choosing "New" (see the wand icon at the upper left corner of the explorer view) and selecting "Container page" in the appearing dialog. Click "Continue" and set the file name to "index.html".

In order to check if everything works fine, go to the index.html directly in the main folder of your site or subsite. You should see your template JSP coming up and the toolbar of the page editor should appear at the top.

This step is most likely dependent on the HTML prototype and can only be described as a general example. Imagine the HTML for the navigation looks like:

<div id=”main-nav”>
	<ul>
		<li>Nav entry1</li>
		<li>Nav entry2</li>
	</ul>
</div>

Then cut the surrounding <div>-element with its inner HTML and add a line like the following in its place:

<cms:include file="%(link.weak:/system/modules/my.template/elements/main-nav.jsp)"/>

Save and close the main.jsp and create a new JSP file at: /system/modules/my.template/elements/main-nav.jsp. Paste the content cut before into the newly created JSP. Afterwards repeat these steps for all dynamic parts of the main.jsp, except the main textual content. When you have finished, you should be able to click on the index.html that uses your template within the explorer view and the template prototype should still be displayed properly.

Note that, alternatively to using includes, you could make everything, for example also navigation elements, a content. This may allow you a more flexible design, in particular with nested containers. But, it's typically also more work. For the tutorial, we stick to the traditional approach of using includes.

This part can also only be described in an abstract way because these steps depend on the specific project requirements. Anyway, the following description should be enough to get a picture of what needs to be done. Let’s make the main navigation shown above dynamic by copying and pasting the content of the file nav_main.jsp from the modules-v8 into the main-nav.jsp created one step before. Have a look at the section about the OpenCms JSP API of this documentation in order to get an impression about how to use the OpenCms specific tag library. A good starting point is also to "copy" from the current demo template shipped with OpenCms. Find more information about building navigation here.

Step 8: Define content types

We have to fill the containers of the template with content. Therefore, we need content that fits into the containers. Use the HTML prototype's dummy-contents to extract which content types you need. Find out if you will need some lists or detail pages. Either create new modules for the content types or add them in your module my.template. Use the  to add new content types.

Here are some more links that may help you:

Go to the sitemap editor in the (sub-)site using your template. Choose the view "Templates" and adjust either the already existing template model(s) or add new ones. Template models are the master copy used when creating new pages via the sitemap editor. The models can already have set specific properties and contain content that should be placed on all pages created by the model. Learn more about creating template models here.

Once you have your template models, use the sitemap editor to add new pages to your website. Edit the pages via the page editor. Drag-and-drop contents to them and edit the contents. And that's it. Congratulations to your new website!