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.
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
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
toprovider=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"
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
For all other containers do not set detailview
to true
.
- Detour to some advanced usage of the
<cms:container>
-tag. - Checkout the TLD-doc of the
<cms:container>
-tag.
<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:
Then cut the surrounding <div>
-element with its inner HTML and add a line like the following in its place:
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.
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.
Rounding up
Of course, this tutorial can not capture all aspects of creating a website. For example, we have not discussed directly:
- What's a good module structure for your website's resources?
- What's the best design for your template? (includes vs. contents)
- How to generate multi-lingual websites?
- ...
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.