The <cms:include> tag

This tag is used to include files from the OpenCms VFS dynamically at runtime. The included file is treated like a request with optional additional request parameters.

There are different options to determine the name of the included file by using one of the following attributes:

  • page
  • property
  • attribute

If none of these attributes has been set, the body of the <cms:include> tag is evaluated and the result is used as filename.

Note: If no filename can be determined by any of the above mentioned methods, then the value of the getUri() method of the current CmsRequestContext is used.

Attributes:

Name Description Required
page (file) The value of this attribute specifies simply the name of the file which is included. The attribute names "page" and "file" are equivalent. no
property The value of this attribute is the name of a property on the JSP file, which in turn specifies the name of the file which is included.
attribute The value of this attribute is the key of an entry in the request attributes hashtable with the name of the file to be included. You then have to set the filename programmatically in the request parameters in your Java source before.
element If the included JSP page is split into elements by the cms:template tag, only the specified element of the JSP page is included. Otherwise, the complete JSP page is included, even if the page is split into elements!
Note: The element attribute is treated as an additional request parameter in the request context.
suffix Appends a suffix string to the filename included via the property attribute or the attribue attribute.
cachable If this attribute is set with the value "false", the included file will not be cached by the Flexcache.

Body:

You can use scriptlet code to determine the included filename in the body if none of the attributes page/ file, property or attribute is used.

You can add additional key/value coded parameters to the request parameters hashtable to pass them to the included file, e.g. <cms:param name="myparam" value="myvalue" />.

Example usage:

Include the JSP page "some_page.html":

<cms:include page="some_page.html" /> or <cms:include file="some_page.html" />

Read the name of the file to be included from the property "template" on the current file, append additionally the suffix "_head.jsp" to the filename (the "suffix" attribute is optional):

<cms:include property="template" suffix="_head.jsp" />

Evaluate the tag's body content to get the name of the file to be included by processing a property tag:

<cms:include>

<cms:property name="template" file="parent"/>

</cms:include>

Include a file by setting its filename in the request attributes hashtable, add additionally some key/value coded parameters to the request parameters hashtable to pass them to the included file:

<%

...

request.setAttribute( "body", "../elements/template-body.html" );

...

%>



<cms:include attribute="body">

    <cms:param name="__locale"><%= locale %></cms:param>

</cms:include>

Include the file specified in the "file" attribute, add additionally some key/value coded parameters to the request parameters hashtable to pass them to the included file:

<cms:include file="../elements/template-nav-top.jsp">

    <cms:param name="__locale"><%= locale %></cms:param>

    <cms:param name="__navpart" value="toprow" />

</cms:include>

Include the element "head" from the JSP page specified by the "template" property:

<cms:include property="template" element="head" />