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 presented content. Following the steps described here, you should be able to get your JSP template up and running in a short time.

Page Navigation

1 Before you start

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 the JSP-/Servlet-Technology in general you will need to learn something about the OpenCms tools and libraries needed to build up a template.

2 Step 1: Creating a new module

The basic functionality of OpenCms is the core system. All additional features including the template that renders the website itself are encapsulated into modules. Commonly one could say that modules are extensions, plugins or packages that are easily to install and extend the basic core functionality for further features, functions, content types, layouts and so on. Modules contain all resources (source files, images, style sheets, JSPs, property files, configurations …) that are required for a demarcated functionality. All modules are located at /system/modules/ in the root site of the VFS. In general there is no convention about the module structure, but of course there are best practices. This chapter gives a brief introduction on how to create and structure a module.

The administration view of the workplace offers a tool to manage modules. 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. If you check all the options a folder /system/modules/my.template/ is created and it contains the following sub-folders:

templates/: Should contain the main template JSP(s), usually a single file main.jsp.
elements/: Should contain elements (JSPs) included by the template (main.jsp), for example a file navigation.jsp.
formatters/: Should contain formatters (JSPs) for content and their configuration files, e.g., an article-formatter.jsp and an article-formatter-configuration.xml
resources/: Should contain static resources referenced by the template, e.g. CSS-files, JavaScript-files, images, etc.).
schemas/: Should contain content type definitions (XSDs), that describe the structure of content types, e.g., an article.xsd that describes the structure of an article.
classes/: Should contain resources that must be exported to the WEB-INF/classes/ folder of the RFS, e.g., Java classes or Java property files.

3 Step 2: Get the HTML prototype into OpenCms

If the HTML prototype is zipped and you have named the just created module 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”, select the JSP radio button and confirm. With a click on the main.jsp a new browser window should open that shows the prototype correctly.

4 Step 3: Adjust links to referenced resources

Open the main.jsp with the code editor and add the following line to the beginning of the file:

<%@page buffer="none" session="false" taglibs="c,cms,fmt,fn" %>

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>"

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

5 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 section for the main content. Remove the HTML and place the following <cms:container>-tag instead. This will enable the content manager to place elements easily via “drag & drop”.

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

6 Step 5: Configure "Advanced Direct Edit"

Create a sitemap folder using the explorer new wizard (“New” -> “Extended folder” -> “Subsitemap folder” -> “Continue” -> enter a name e.g. “en” -> let the checkbox “Edit properties of the new file” checked -> “Continue” -> “Advanced” -> enter into the "template"-property: /system/modules/my.template/templates/main.jsp -> “Finish”)
Create container page /en/index.html (Click on the folder “en” -> “New” -> “Container page” -> “Continue” -> enter “index.html” -> uncheck both checkboxes -> “Finish”)
Create a “/en/.content/”-folder (“New” -> “Extended folder” -> “Sitemap content folder” -> “Continue” -> “.content” -> uncheck checkbox -> “Finish”)
A sitemap configuration e.g. “/en/.content/.config” is being created automatically
Create a folder “/en/.content/.new/” (Left click on the folder “.content” -> “New” -> “Folder” -> “Continue” -> enter “.new“ -> uncheck checkbox -> “Finish”)
Create an empty page model “/en/.content/.new/default.html” (see step 2)
Configure a previously created page model for the sitemap (Right click on ”/en/.content/.config” -> “Edit” -> Open the “Model pages”-tab -> Add a “Model”-node by clicking the plus and enter “/en/.content/.new/default.html” -> “Save and close”

7 Step 6: Create a navigation structure

In order to validate that everything works fine so far, click on the index.html. The template should come up and you should be able to activate the toolbar by clicking on the “bull’s eye” on the top right of the page. If the model page has been configured correctly, open the sitemap and start creating a navigation structure. For more information about using the sitemap, please read about the sitemap editor.

8 Step 7: Devide the prototype into separate elements

This step is most likely dependent on the HTML prototype and can only be described as 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 at that 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 the work, you should be able to click on the main.jsp within the explorer view and the template prototype should be displayed properly.

9 Step 8: Make the extracted elements dynamic

This part can also only be described in an abstract point of view because these steps are depending on the specific project requirements. Anyway, the following description should be enough to get a picture of how the work can look like. Let’s make the above shown main navigation dynamic by copy and paste 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. Or learn how to create lists of resources and detail pages by reading the section about lists of resources and detail pages. And again the modules-v8 is a good starting point to learn more about writing JSPs or to “copy and paste” code that can be adjusted according to your needs.

10 Step 9: Start the content creation

Read the topics on content in OpenCms and the page editor to learn how to create and use resource types.