How to use "includes" in OpenCms

Constructing a page by combining different elements is an often used approach for web site building. There are many options to achieve this with OpenCms, which are explained below:

Preferred ways of including

Directive based inclusion with <%@ include file="..." %>

In case you just want to statically include a file at compile time, you can use the standard directive <%@ include file="..." %>.

To include a file from within the VFS, you have to add the path to the included file in a special makro, to use the benifits of the content relationship engine. For example if you want to include the file "/system/modules/mymodule/elements/myjsp.jsp" you have to use it within a mako like this: <%@ include file="%(link.strong:/system/modules/mymodule/elements/myjsp.jsp)" %>. 

Keep in mind that OpenCms will automatically translate the given file name to /WEB-INF/jsp/{on/offline}/{original-filename}, so all inclusions happen from the "real" FS, not from the VFS. That translation will happen while the JSP is written from the VFS to the "real" FS. OpenCms will insure that all files referenced by <%@ include file= "..." %> directives will also be written to the "real" FS.
Please note: The XML - translation form of this directive <jsp:directive.include file="..." /> is currently NOT supported!

Use the <cms:include page="..." /> tag

This tag is part of the OpenCms standard taglib. It is the best method of including elements in an OpenCms based application during runtime. Usage of <cms:include> also enables the FlexCache to separately cache the included sub - element, which can result in much faster page delivery times. For a complete description of all the tags options, please see the OpenCms taglib documentation available from Alkacon as a separate module.

Use the include() method of the class CmsJspActionElement

This executes the same code as using the <cms:include> tag, but it can be used directly inside a JSP scriptlet. You just have to create an instance of the JavaBean org.opencms.jsp.CmsJspActionElement and use the provided methods. This option also supports the FlexCache and all the other options that the tag version supports. Again, for a complete description please see the OpenCms scriptlet documentation available from Alkacon as a separate module.

Options not recommended

JSP inclusion with <jsp:include page="..." />

The short version: Tests have shown that this will not work reliable in all servlet containers or container versions even when used as pointed out below, so we do not recommend using this option. Use the OpenCms <cms:include> tag instead.

The long version: Using <jsp:include page="..." /> in OpenCms managed JSP is a tricky issue. The point is the OpenCms servlet which always comes first and then dispatches to the JSP. This additional servlet "confuses" the container, so using something like <jsp:include page..." /> will sometimes give an undefined result. To overcome some of this issues, a new directive <%@ cms file="..." %> has been introduced. This directive is replaced with the filename on the "real" FS when OpenCms parses and dumps the file initially from the VFS to the "real" FS. So you could actually use <jsp:include page="<%@ cms file="/index.jsp"%>" flush="false" /> to achieve the wanted results. The FlexCache is bypassed when using this approach. You must set flush="false" because in the current implementation OpenCms is not able to handle flush="true".

In case you find this mind-boggling, just use <cms:include page="..." /> instead.

The tag <c:import /> from the JSTL for local files

The JSTL adds a new way of doing inclusions with the <c:import /> tag. There is a whole set of examples available in the com.alkacon.documentation.examples_jstl module. It turns out that using <c:import /> works fine when used with external URLs. However, importing local / relative URLs is subject to the same issues as using <jsp:include page="..." />, so you have to use <%@ cms file="..." %> around filenames here as well.

Again, the recommended way of doing file inclusions in OpenCms is using the <cms:include page="..." /> tag!