OpenCms Documentation

Creating a template JSP

 Show GitHub edit links  Hide GitHub edit links
Documented since: 8.0 Latest revision for: 9.5 Valid for OpenCms: 13.0

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.

Before you start

The first step in developing a template is the design. It is assumed you have a HTML <div>-based layout in a file called index.html that refers the needed resources relatively to the index file itself. The structure should look like:

templates/index.html
templates/index2.html
resources/css/screen.css
resources/css/print.css
resources/img/image1.png
resources/img/image2.png
resources/img/image3.png
resources/img/image4.png
resources/js/page.js

In the tutorial, we assume you have the above structure present in a ZIP file. We call the structure HTML prototype.

In addition to a good knowledge about JSP/servlet technology in general you will need to learn something about the OpenCms tools and libraries needed to build up a template.

Step 1: Creating a new module

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

After Logging into the workplace switch to the “Administration View” and select “Module Management” -> “New Module”. In the upcoming dialog you will be asked to enter a package name that must fulfill the Java package name conventions. Please use my.template as package name if you follow this short tutorial. Moreover, you can enter a nice name and a module description as well as a module number, a group and optionally a module action class. Below the author information you can select 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.

After you filled out the dialog, click ok and the module, as well as the checked module folders will be created.

Step 2: Get the HTML prototype into OpenCms

If the HTML prototype is zipped and you have named the module you just created my.template, go to the folder /system/modules/my.template and upload the ZIP file with the ZIP-inflating option. Afterwards go to /system/modules/my.template/templates/ and rename the index.html to main.jsp, then right click on main.jsp and choose the option: “Advanced” -> “Change type”, choose the "Configurations" group and select "Page template". With a click on the main.jsp a new browser window should open that shows the prototype correctly.

At the main.jsp, set the (individual) properties

  • template.provider to provider=org.opencms.loader.CmsDefaultTemplateContextProvider,template=%(templatepath).This will cause the use of a template context provider, adding features for device dependent representation when you choose the template from the drop down list.
  • 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/screen.css.This will cause the style to be used in HTML editor when editing content.

Step 3: Adjust links to referenced resources

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 referenced links by replacing the href and the src attribute values according to the following examples in order to keep internal links intact:

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

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

As an alternative to the adjustment described here, you could also use the defaults attribute of the <cms:headincludes>-tag.

Step 4: Insert containers and enable "Advanced Direct Edit"

Enable ADE features by adding the following tag in the head section of your main template.

<cms:enable-ade />

Somewhere in the prototype there might be a sections with content that should be addable via drag&drop. Remove the HTML of these sections and place <cms:container>-tags instead. This will enable the content manager to place elements easily via “drag & drop”. For the main content part you could choose the tag like

<cms:container name="centercontainer" type="center" 
               width="500" maxElements="8" detailview="true"/>

For all other containers do not set detailview to true.

When your JSP contains a <cms:container>-tag you cannot preview the JSP directly anymore. You must use a container page using the template to see a preview. (See the next step on how to create one.)

Step 5: Configure your template for a site or subsite

If you want to set your template for an existing site or subsiteOf course, you can also create the subsite first using the sitemap editor., go to the sitemap editor, choose the "Resources" view and select "Properties" from 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 provider=org.opencms.loader.CmsDefaultTemplateContextProvider,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 upper left corner of the explorer view) and selecting "Container page" in the appearing dialog. Click "Continue" and set the file name, thus that is "index.html" in the end.

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 an edit point in the upper right corner. If you click it, the menu of the page editor should appear.

Step 6: Divide the prototype into separate elements

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.

Step 7: Make the extracted elements dynamic

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.

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:

Step 9: Create template models

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 owns. 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.

Step 10: Create the pages of your website

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&drop content to them and edit this content. And that's it.

Congratulations to your new website!

Rounding up

Of course, this tutorial can not capture all aspects of creating a website. For example, we have not discussed directly:

Check out the documentation for answers to these and other questions. We try to add information with every update - and will also try to link to it.