Embeddable Content Viewer Pages

This page is defined by the /pages/viewer.ftl and /pages/mapViewer.ftl (deprecated) templates in the portal theme. Content that can be embedded in a portal's overall look, such as XML content, Markdown, and some HTML files, are rendered through this template. Other file types are served directly, without a template.

If the document is a contextualized DITA topic - that is, a topic that is part of a map - it will be rendered using viewer.ftl. All other file types will be rendered using mapViewer.ftl.

Important: mapViewer.ftl is deprecated. It is strongly recommended that all viewer page logic be placed in viewer.ftl, and that mapViewer.ftl simply be an inclusion of viewer.ftl. The Freemarker code can determine whether the document is a contextualized topic using the hasContext variable. The mapViewer.ftl template may be removed in a future release.

Note: When providing links to the viewer page, it is strongly advised to use the tag, specifying a object for the tag's @searchResult attribute.

Tip: In addition to the URL format returned by the viewerUrl tag, you can use metadata to construct the web URL to the viewer pages using query parameters. By accessing /portalUrlPath/viewer?<md_name>=<md_value>. You can specify as many metadata parameters as you want. If more than one file matches the metadata query, the system will pick one at random.

So, for example, if you wanted to access a DITA topic with <resourceId id="12345"/>, you could use /myportal/viewer?resourceid=12345.

Variables

In addition to the common properties, this page has access to the following:

itemUrl: The for the file being displayed. In the case of a DITA topic under a map, this will be the locator for the topic. In the case of a synthetic topic generated from a heading-only node in a DITA map, this will be the locator of the map. In the case of a chunked division in a non-DITA document, this will be the locator for the top-level document.
contextRefId: Only present when viewing a piece of content in the context of another, such as a DITA topic or XML division chunk. In the case of a DITA topic within a map, this will be the ID of the topicref element referencing the topic. In the case of a chunked division, this will be the ID of the element defining the chunk.
virtual: A boolean attribute describing whether the content being viewed is a virtual chunk, meaning that the content was generated as part of content processing, and was not based on a file in a project. This will be false for DITA maps and topics, and for top-level non-DITA documents. It will be true for chunked divisions in non-DITA documents and for topics generated from title-only <topicref> elements in DITA maps.
title: The title of the document being shown. In the case of contextualized content such as a DITA topic in a map or a chunked division, this will be the title of the topic or chunk. In the case of monolithic XML documents or root-level DITA maps, this will be the title of the document itself. In the case of chunked divisions, this is the only way to get the title of the chunk, as all other document properties listed here will be associated with the top-level document.
itemData: An data structure with access to the properties of the document identified by itemUrl.
properties: A hash containing the file's properties. A convenience synonym for itemData.propertyMap.
metadata: A hash of all of the properties for the file being viewed, including project and context metadata, if any.
Note: This is not a synonym for itemData.properties, which only contains only the metadata for the item itself.
contexts: An array of data structures that represent the various contexts in which this file is present. Only those contexts visible to the portal (as determined by metadata rules) will be included.
hasContext: A boolean value denoting whether the object being viewed is contextualized under a DITA map.
contextHarpUrl: The of the context (usually a DITA map) for the content being viewed. Optional, and will never be present in mapViewer.ftl.
contextMetadata: The hash of properties for the context (generally a DITA map) of the file being viewed. Optional, and will never be present in mapViewer.ftl.
debug: The boolean value represented by the optional debug URL parameter. Can be used to trigger special debugging behavior. Always present, defaults to false.
ignoreCache: The boolean value represented by the optional ignoreCache URL parameter, and can be used in conjunction with the ignoreCache attribute on the tag to bypass server-side caching mechanisms. Always present, defaults to false.
UUID: A generated UUID that can be used to identify individual page views for analytics recording purposes.

Note: In most cases, the document being viewed is a file in a project. However, in some cases, these pages will be used to view content for which there is no corresponding document in a project. These include

Synthetic DITA topics defined by a title-only <topicref> element.
A chunked division from a non-DITA document.

In such cases, the metadata properties will be describing the top-level document/DITA map instead of the chunk being viewed. The one exception to this is title, which will always be the title of the chunk being viewed, regardless of whether or not it is virtual.