Why using OpenCms features in a JSP?

OpenCms offers you a lot of features that can help you speeding up the development process, like templates, user management and a declarative permission and caching system. Also you probably want to build dynamic navigations based on your OpenCms file structure. All files in OpenCms are located in the OpenCms "Virtual File System" (or VFS), which is stored in the attached database. To access any information in the OpenCms VFS you will need to use the OpenCms JSP API.

The basic options

In your JSPs you have two options to access the OpenCms functionality:

1. Using the OpenCms taglib (which usually starts with the <cms:> tag)
2. Using the OpenCms org.opencms.jsp.CmsJspActionElement in a JSP scriptlet

You can use both methods to achieve the same basic results, this is a matter of personal style and experience. In general, JSP taglibs are easier to use for the novice Java programmer and there is a chance that even non-Java but HTML experienced people can create results using taglibs in the same manner as HTML tags. On the other hand, the experienced Java veteran might prefer using scriptlet code (with JavaBeans for business logic), to obtain more control and better performance.

If you are using the OpenCms taglib, you should consider combining it with a "general purpose" taglib for basic things like loops, if - then decisions, enumerations etc. A good choice for that is the JSTL (Java Standard Tag Library) which is a standard JSP 2.0 feature. There is a documentation module available from Alkacon that lists a lot of JSTL examples.

In case you want to build advanced functionality in OpenCms (like navigations or forms) you will need to use the scriptlet API.

Please note that two separate documentation modules exist for each of these options (taglib and scriptlet developing), in which all details are explained. And in case you want to build templates in OpenCms, there is a separate "Howto" module for this available as well. The examples on this page are just intended as a short introduction and not as a complete reference.

The OpenCms <cms:> taglib

If you want to use the OpenCms taglib you just have to declare it like this on your JSP page:

<%@ taglib prefix="cms" uri="http://www.opencms.org/taglib/cms" %> 

<h1>Simple taglib example</h1> 

The installed OpenCms version is <cms:info property="opencms.version"/>.<p> 

The "title" property of this file is "<cms:property name= "title"/>".<p> 

Link to a file in the OpenCms VFS:
<a href="<cms:link>/alkacon-documentation/index.html</cms:link>">like this</a>.<p>

You can see this example in action in the file example-taglib.jsp.

You can combine the OpenCms taglib with other taglibs, for example with the Java Standard Taglib Library (JSTL). There is a separate example module available that shows the usage of the JSTL in OpenCms. How to install and configure other taglibs in general is outside the scope of this documentation.

The OpenCms scriptlet API

To access the OpenCms API in your scriptlet code, create an instance of the JavaBean org.opencms.jsp.CmsJspActionElement,like in this example:

<%@ page import="java.util.*,org.opencms.jsp.*" %><%	

// Create a JSP action element
CmsJspActionElement cms = new CmsJspActionElement(pageContext, request, response);

// Get a simple navigation of all pages / subfolders in the current folder 
List list = cms.getNavigation().getNavigationForFolder();
Iterator i = list.iterator();

out.println("<h3>A simple sample navigation</h3><ul>");
while (i.hasNext()) {
	CmsJspNavElement ne = (CmsJspNavElement)i.next();
    out.println("<li><a href=\"" + cms.link(ne.getResourceName()) + "\">");
    out.println(ne.getTitle() + "</a>");
}    
out.println("</ul>");
%>

It's outside the scope of this documentation to explain everything in this example, but the more experienced Java developers should get the idea.

You can see this example in action in the file example-scriptlet.jsp.

Conclusion

To get more comfortable with the OpenCms JSP API, you should install additional example modules and have a close look on the source code of some of the provided examples. Also you will need to study the two already mentioned documentation modules for the OpenCms taglib and scriptlet API, which are named com.alkacon.documentation.documentation_taglib and com.alkacon.documentation.documentation_scriptlet.

Continue with the advanced JSP topics to learn about other details of the JSP integration in OpenCms.