JSON support

This following  assumes that in your JSPs, you include the OpenCms tag library as follows:

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

When the URL of an incoming request contains the request parameter "__json=true", JSON conversion is activated for this request. This means that instead of rendering the page by default, OpenCms produces JSON output that contains selected sections of the page's HTML as JSON values.

The <cms;jsonpart> tag can be used to control which parts of the JSP output should be used as JSON values, and the element attribute of the tag is used to control the JSON key for the value produced from the tag's body.

For example, the output of the JSP code:

<%@ taglib prefix="cms" uri="http://www.opencms.org/taglib/cms"%>
lorem ipsum<
<cms:jsonpart element="part1">this is the first part</cms:jsonpart>
lorem ipsum
<cms:jsonpart element="part2">this is the second part</cms:jsonpart>

will, when in JSON conversion mode, be converted to the (approximate) JSON output:

{
"part1": "this is the first part",
"part2": "this is the second part",
"parts": ["part1", "part2"]
}

(Note that spacing/newlines have been adjusted in this example to increase readability. The actual output will look more messy.)

When not in JSON conversion mode, the <cms:jsonpart> tag will leave its content's output unchanged, i.e. the output will be the same as if the tags weren't there.

In JSON conversion mode, everything except the parts of the page enclosed by these tags is thrown away, and the response text will consist of a single JSON object  with the key-value pairs described above.

An additional key-value pair with the key "parts" is added to this object, which contains an array of the other key names, in the order they were processed while rendering the original page.

<cms:jsonpart> tags may not be nested either directly in the same JSP file, or indirectly, i.e. by including a JSP file using <cms:jsonpart> inside the body of another <cms:jsonpart> tag.

Note that the tag does not require that the output of its content is valid HTML; it is your responsibility as a developer to ensure this if the application consuming the JSON output requires valid HTML as JSON values.

In some cases, it might be useful to detect in your JSP whether the current request is running in JSON mode or not. This can be checked by using the attribute "isJSONRequest" on the CmsJspStandardContextBean instance commonly available in EL expressions under the name "cms":

If a page, when requested, would produce an HTTP status code which is not 200, then the response when requesting the same page in JSON mode will not, in general, be usable JSON.

If, while in JSON conversion mode, an exception is thrown and not caught while inside the body of a <cms:jsonpart> tag, but caught before escaping the top-level JSP, then valid JSON will be returned in the response, but the value corresponding to the <cms:jsonpart> tag from which the exception originated will be truncated and contain only the output which was printed before the exception was thrown.

The functionality described above relies on a special servlet filter, which is enabled by default on a freshly set up OpenCms instance.
If you are using an OpenCms instance which was updated from an earlier version and haven't replaced your web.xml file, you may need to configure this filter manually.  

Ensure that your WEB-INF/web.xml contains the following entries: