Creating a template JSP

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:

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

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.

• Get more information on the module system and what to package how.

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.

• Get more information on managing modules here.

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.

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:

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:

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

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

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.

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.

• Get more information on the sitemap editor.

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.

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.

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.

• Here's more information on building a navigation.

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.

• Use the basic tutorial to find out how to define a resource type.

Here are some more links that may help you:

• Read about the "Add resource type" tool from the module administration
• Read the topics on content in OpenCms.
• Checkout what you can do with the page editor.
• Learn about lists and detail pages.

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.

• Learn how to create and use template models.

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.

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.