Titania Delivery Developer's Guide

Page Variables

This page has access to all of the common variables.

This page is populated with search results from the following query parameters:

escape

Either true or false. Specifies whether special query characters in the term should be escaped when executing the query. The default is false. See Search Syntax for details of reserved search characters.

facet

A metadata field to use as a search facet. If not specified, the search facets configured for the portal are used. See the Titania Delivery Administrative Guide for details on configuring a portal's default search facets. This parameter may be specified multiple times to specify multiple metadata fields to use as facets.

filter

A secondary search query to use to filter the available documents that should be included in the results. The same results could be achieved by adding additional criteria to the term, but there are performance benefits to using a separate filter parameter, especially when the same filter may be reused for multiple searches.

groupBy

The property for grouping results. Default is itemKey.

groupSize

The maximum number of contextualized DITA topics to include in result groupings. The default is 5.

highlightSize

The maximum number of characters to include in text snippets containing matching text. The default is 300.

maxFacetValues

The maximum number of facet values to include in the search results. The default is 10.

n

The number of search results to return per page. If not specified, the default is 10.

page

The zero-based index of the page to view. The default is 0.

portalContent

Portals can generate files using the siteData interface. This parameter specifies if and how content in that project should be included in the search. The valid values are:

exclude

Portal-generated content is excluded. This is the default.

include

Portal-generated content is included, along with other content available through the portal.

only

Only portal-generated content will be included in the results.

sortBy

The property name or names by which to sort the results. (All metadata values are indexed as keywords, and must be named with '_md' suffix: for example, sortBy=title_md.) Multiple names may be specified, separated by spaces or commas (URL-encoded as necessary). Multiple sortBy parameters may be included, but since the order of parameter processing is not guaranteed to be consistent, it is advisable to use only one sortBy parameter if corresponding sortDirections are specified.

Note: Sort keys given in the sortBy parameter will be used before the default "relevance" (as determined by the search engine) is applied. So the top items in the result list might not be the "most relevant" based on the search term.

sortDirection

Specify the sort directions corresponding to each sortBy field. If the list of sort directions is empty or shorter than the list of sortBy fields, the default order is ASC. Values may be either ASC or DESC (case-insensitive) to specify the sort direction as ascending or descending. Multiple sortDirection parameters may be included, but since the order of parameter processing is not guaranteed to be consistent, it is advisable to use only one sortDirection parameter (with multiple values, if necessary).

startAfter

For programmatic use only, this should be an object value from the SearchResultsPage startNextAfter property.

term

The search query.

Additionally, any number of metadata filters can be supplied, each in the format: f.[metadataName]_md. All parameters are optional but if a term parameter is not supplied the search results will be empty.

For example, assume the search page is requested with the following URL query string: ?term=Titania&n=5&page=1&f.format_md=dita. The page would be populated with data containing up to five search results of the second page (remember that the page param is zero-indexed) of results that match the search term Titania that have format metadata with a value of dita.

• Search results for the word "Titania"
• Up to five results
• Starting with the sixth result, because we requested the second page (because the page parameter is zero-indexed).

Data Model

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

filterParams

A string containing the URL parameters for the metadata filters being applied to the search. This is a convenience property that could be constructed manually from the filters data structure. This property can be used to easily construct URLs in paginated search result lists.

filters

A hash. The keys of the hash are the metadata names being used to filter results. Each keyed entry is an array of the values for that metadata name specified by the user for filtering.

For example, if a user filters on a metadata named "foo" using values "abc" and "xyz", the ${filters} hash would look like this:

{
  foo: ['abc', 'xyz']
}

result

A SearchResultsPage containing the set of results to display, grouped by context, represented by SearchResultGroup objects.

sortBy

Sequence or null. If sortBy names were given, this will be a sequence of the given sortBy field names.

sortDirection

Sequence or null. If sortDirection parameter was given, this will be the sequence of values specified.

term

The search term entered by the user.

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.

Variables

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

itemUrl

The ContentLocator 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 ItemDataAccess 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 ContentRelationship 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 ContentLocator 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 <@td.content> 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.

This page is only required for portals secured using LDAP. If a user is not logged in or their session has recently expired and they attempt to visit any page within the Portal, they will be forwarded to this page if the Portal does not support anonymous browsing. Attempting to access the login page in a Portal without security will redirect to portal-home.ftl. In order to log in, a client must send a successful POST containing valid username and password parameters to the URL below. If their information matches the credentials stored in the server connected to by the LDAP configuration set up on the admin application then they will be forwarded to the portal. If the request was unsuccessful for any reason, the user will be redirected to login.ftl and there will be an error message added to the model.

The most basic login.ftl should contain the following contents:

<!DOCTYPE html>
<html lang="en">
<head>
 <meta charset="utf-8">
</head>

<body>

 <#if errorMessage??>
  ${errorMessage?html}
 </#if>

 <form action="login" method="post">
  <label for="username">User Name</label>
  <input type="text" name="username" placeholder="User Name">
  <label for="password">Password</label>
  <input type="password" name="password" placeholder="Password">
  <button type="submit">Submit</button>
 </form>

</body>

</html>

Page Variables

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

errorMessage

A string with the error message produced by the previous login attempt.

Page Variables

In addition to the common variables, these pages have access to the following:

assembly

The Assembly object.

assemblyTopicRef

The ID for the document in the assembly being viewed. Applies only for assemblyTopicViewer.ftl.

ignoreCache

The boolean value represented by the optional ignoreCache URL parameter, and can be used in conjunction with the ignoreCache attribute on the <@td.content> 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.

Page Variables

Unlike most pages, error pages do not include the common variables. Error pages are limited to the following data:

portal

A complex object containing the properties of the portal itself. See PortalIdentity.

request

The HttpServletRequest object for the current request.

errorCode

An integer with the HTTP error code.

stackTrace

If applicable, the Java exception stack trace that caused the error page.

Custom pages can be linked to via <a href=<@harp.pageUrl page="path/to/custom/page.ftl" />>Link Text</a>. The path must be relative to the /pages/custom/ directory.

Page Variables

In addition to the common variables, all custom pages have access to the following:

multiValueParams

A hash of the URL request parameters, with all values for each parameter in a string array.

params

A hash of the URL request parameters, holding a single value for each parameter. (Do not use for multi-value parameters.)

requestBody

An HttpEntityContent object representing the HTTP request body (if any).

UUID

A generated UUID that can be used to identify individual page views for analytics recording purposes.

Specifying Content Type via File Extension

By default, the Content-Type header for custom pages is text/html. However, if the base name of the file has an extension with a known file type, the system will automatically select the appropriate value for the Content-Type header. For example, the custom page template /pages/custom/example.css.ftl would be served with a Content-Type header of text/css.

Here are some common file extensions and the resulting content type.

HTTP Headers for Custom Pages

By default, Titania Delivery serves custom pages with a minimum of HTTP headers, and a Content-Type header determined as described above. You can customize the HTTP headers sent for a given custom page by specifying those headers in metadata with keys beginning with _td.header.. For example, specifying _td.header.Content-Type=application/xml on a page's metadata will cause it to be served as an XML document.

Instantiation

Instances of sets and lists are instantiated using the newSet or newList objects. These objects can be invoked as either directives or functions.

<#-- As a directive -->
<@newSet var="mySet"/>
<@newList var="myList"/>

<#-- As a function -->
<#assign mySet = newSet()/>
<#assign myList = newList()/>

Once instantiated, the variable can be used as a prefix for the various directives and properties of the collection.

Parameters

var or assign

The global variable name to assign the new object. This parameter cannot be passed to the functional form.

<@newSet var="mySet"/>
<@newSet assign="mySet"/>
<#-- Identical to: -->
<#assign mySet = newSet()/>

local

The local variable name to assign the new object. The current processing context must be within a <#function> or <#macro>. This parameter cannot be passed to the functional form.

<@newList local="myList"/>
<#-- Identical to: -->
<#local myList = newList()/>

from

Optional. A Freemarker sequence that will be the starting values for the object. Passed as the first argument to the functional form.

<@newSet var="mySet" from=['a', 'b', 'c']/>
<#assign mySet = newSet(['a', 'b', 'c'])/>

Directives

Sets provide sub-directives that can be used to modify the contents of the set.

add

Used to add values to the set using the value parameter.

<@mySet.add value="someValue"/>

clear

Removes all values from the collection.

<@myList.clear/>

removeValue

Removes a value from the collection using the value parameter.

<@mySet.removeValue value="someValue"/>

removeIndex (lists only)

Removes a value from a list using the index parameter.

Important: This directive is not present on sets, and attempts to invoke it on sets will cause errors.

<@myList.removeIndex index=4/>

Properties

Sets and lists have the following properties.

size

The number of elements in the collection.

${mySet.size}

asSequence

The collection as a native Freemarker sequence. This is the primary mechanism by which the data in the collection should be read.

Note: There is no meaningful processing or memory overhead when using this property. It is a reference to the underlying storage for the object, it is not a copy.

${myList.asSequence[0]}
${mySet.asSequence?join('<br>')}
<#if myList.asSequence?seq_contains('someValue')>
  <#-- Conditional code here -->
</#if>

json

The set as a JSON string.

<pre>${mySet.json?html}</pre>

Instantiation

<#-- As a directive -->
<@newMap var="myMap"/>

<#-- As a function -->
<#assign myMap = newMap()/>

Parameters

var or assign

The global variable name to assign the new object. This parameter cannot be passed to the functional form.

<@newMap var="myMap"/>
<@newMap assign="myMap"/>

local

The local variable name to assign the new object. The current processing context must be within a <#function> or <#macro>. This parameter cannot be passed to the functional form.

<@newMap local="myMap"/>

from

Optional. A Freemarker hash that will be the starting entries for the map. Passed as the first argument to the functional form.

<@newMap var="myMap" from={"index": 5, "title": "Some Title"}/>
<#assign myMap = newMap({"index": 5, "title": "Some Title"})/>

Directives

Maps provide sub-directives that can be used to modify the contents of the map.

put

Used to add entries to the map using the key and value attributes. The key must be a string. The value can be anything.

<@myMap.put key="someKey" value="someValue"/>

clear

Removes all entries from the map.

<@myMap.clear/>

remove

Removes an entry from the set using the key parameter.

<@myMap.remove key="someKey"/>

Properties

Maps have the following properties.

size

The number of elements in the map.

${myMap.size}

keys

The keys in the map as a Freemarker sequence.

<#if myMap.keys?seq_contains('foo')>
  <#-- Conditional code here -->
</#if>

asHash

The map as a native Freemarker hash. This is the primary mechanism by which the data in the map should be read.

Note: There is no significant processing or memory overhead when using this property. It is a reference to the underlying storage for the object, it is not a copy.

${myMap.asHash['someKey']!'No entry for someKey'}
<#if myMap.asHash?keys?seq_contains('someKey')>
  <#-- Conditional code here -->
</#if>

json

The map as a JSON string.

<pre>${myMap.json?html}</pre>

Directives

Layout templates are implemented using the following directives:

<@t.region>

This directive declares a region to be populated in a layout template by client templates. Attributes:

@name

Required. The name of the region.

@renderDefault

Optional; default is true. Specifies whether the contents of the directive should be rendered if not replaced by a <@t.content> directive in the referencing page.

<@t.region.*>

As a shortcut, regions can be declared with their names as part of the directive name, e.g. <@t.region.body/> instead of <@t.region name="body"/>.

<@t.page>

Surrounds content whose overall structure is defined by a layout template. Attributes:

@layout

Required. A relative path to the layout template to use for the contents defined within this page. (The @master attribute may also be used, though this is deprecated.)

<@t.section>

Surrounds content whose overall structure is defined by a layout template. Attributes:

@layout

Required. A relative path to the layout template to use for the contents defined within this fragment. (The @master attribute may also be used, though this is deprecated.)

<@t.content>

This directive is used within <@t.page> and <@t.section> to define content to populate the regions declared by the referenced layout template. If used outside the context of <@t.page> or <@t.section>, causes an error. Attributes:

@region

Required. The name of the region to be populated.

@action

Optional. The allowable values are "replace", "prepend", or "append". The default is "replace". If there are multiple <@t.content> directives for the same region with an action of "replace", only the first will be executed. Multiple "append" actions will be inserted in the order in which they are declared; multiple "prepend" actions will be applied in reverse order.

defer

Optional boolean attribute. If true, render this content when the matching <@t.region> directive is processed. If false, render the contents immediately when the <@t.content> directive is evaluated. This could affect what variables and macros are in scope when the contents of the directive are evaluated.

<@t.prepend> and <@t.append>

These directives are synonyms for <@t.content>, but with the @region attribute set automatically. For example:

<@t.append region="header">
  More header!
</@t.append>

The above is the same as:

<@t.content region="header" action="append">
  More header!
</@t.content>

<@t.content.*>, <@t.prepend.*>, and <@t.append.*>

These directives are synonyms for their base versions, with the @region attribute included in the directive name instead of as an attribute. For example:

<@t.append.header>
  More header!
</@t.append.header>
<@t.content.body>
  This is body content
</@t.content.body>

This is synonymous with:

<@t.content action="append" region="header">
  More header!
</@t.content>
<@t.content region="body">
  This is body content
</@t.content>

Example Page with a Layout Template

<@t.page layout="relative/path/to/page_layout.ftl">
  <@t.content region="title">Page Title</@t.content>

  <@t.content region="head">
    <link rel="stylesheet" href="style.css">
  </@t.content>

  <@t.content region="pageHeader">
    Overriding page header.
  </@t.content>

  <#-- Uses the simplified, collapse model -->
  <@t.content.body>
    <h2>Page Contents</h2>
    <p>This is where the body goes.</p>
  </@t.content.body>

  <@t.content region="pageFooter" action="prepend">
    Extra, PREPENDED footer for this page.
  </@t.content>

  <#-- Uses the simplified, collapse model -->
  <@t.append.pageFooter>
    Extra, APPENDED footer for this page.
  </@t.append.pageFooter>
</@t.page>

Layouts for Page Sections

Layout templates may also be used for document fragments. Syntactically these fragment layout templates are the same as a page layout template, but will have a top-level element representing some type of HTML division element. Like page layout templates, they will contain <@t.region> directives to place and name regions of replaceable content.

<div>
  <h1><@t.region name="section-title"/></h1>
  <@t.region name="section-contents"/>
</div>

<html>
  <head>
    <title>Sections with Common Layout</title>
  </head>
  <body>
    <@t.section layout="relative/path/to/section_layout.ftl">
      <@t.content region="section-title">
        <#-- generate first section title -->
      </@t.content>
      <@t.content region="section-contents">
        <#-- generate first section contents -->
      </@t.content/>
    </@t.section>
    <@t.section layout="relative/path/to/section_layout.ftl">
      <@t.content region="section-title">
        <#-- generate 2nd section title -->
      </@t.content>
      <@t.content region="section-contents">
        <#-- generate 2nd section contents -->
      </@t.content/>
    </@t.section>
  </body>
</html>

Layering Layout Templates

A <@t.page> can reference a @layout which, itself, specifies a <@t.page> directive. Intermediate <@t.page> templates may declare their own <@t.region> directives. Such pages can reference any of the regions at any level of the referenced pages, including the regions in the ultimate layout template.

If a given region is replaced at multiple levels, the first replacing <@t.content> for that region from the outermost page will be used. Prepending and appending content will be applied from all levels, with the outermost page contents coming first for prepending and last for appending.

<@t.page layout="innerPage.ftl">
  <@t.content region="innerPageContent">
    Content from outerPage.
  </@t.content>

  <@t.content region="layoutFooter">
    Footer from outerPage.
  </@t.content>
</@t.page>

<@t.page layout="layout.ftl">
  <@t.content region="layoutContent">
    Content from innerPage.
    <@t.region name="innerPageContent"/>
  </@t.content>

  <@t.content region="layoutFooter">
    This will be overwritten by outerPage.ftl
  </@t.content>
</@t.page>

<@t.region name="layoutContent"/>
<@t.region name="layoutFooter"/>

Content from innerPage.
Content from outerPage.
Footer from outerPage.

Use <#attempt>/<#recover>

Wrapping a section of your template in <#attempt> allows you to handle errors that occur yourself, instead of having the page fail to render entirely. The error will be encapsulated in the built-in .error variable.

<#attempt>
<#-- Risky code here -->
<#recover>
<#-- Error handling here; the error is in the .error variable -->
<pre>${.error?html}</pre>
</#attempt>

Set the ?ftldebug URL parameter

When you add the ?ftldebug parameter to a Titania Delivery portal URL, HTML comments will be inserted around all template <#include> directives. In addition, boundaries around content laid out using the special Layout Templates directives will also be marked. This can significanly help in identifying where the Feemarker code that generated a part of the page is managed.

<!-- START TEMPLATE "/pages/viewer.ftl" -->
<!-- START TEMPLATE "/pages/masters/mainLaout.ftl" -->
<!DOCTYPE html>
<html>
<head>
  <!-- START REGION "htmlHead" from "/pages/viewer.ftl" -->
  <title>Topic Title</title>
  <!-- END REGION "htmlHead" from "/pages/viewer.ftl" -->
</head>
<body>
  <!-- START REGION "body" from "/pages/viewer.ftl" -->
    <!-- START TEMPLATE "/pages/masters/modules/layout.ftl" -->
      Navbar Content Here
    <!-- END TEMPLATE "/pages/masters/modules/layout.ftl" -->
    Contents of the page here.
  <!-- END REGION "body" from "/pages/viewer.ftl" -->
</body>
</html>
<!-- END TEMPLATE "/pages/masters/mainLayout.ftl" -->
<!-- END TEMPLATE "/pages/viewer.ftl" -->

Represents an assembly. Assemblies come in two flavors:

• Created in the admin application, belonging to a project.
• Created by a Portal application, belonging to the portal.

Properties

String key

The unique ID of the Assembly

Date createDate

The date the Assembly was created

Date lastModified

The last-modified date of the Assembly

String name

The title of the Assembly

String refId

The unique identifier for this node within the assembly. Used to identify which document to display when rendering the node in a portal.

Properties

String projectKey

The project key of the item.

String itemPath

The path to the item within the Project specified by projectKey .

String itemKey

The key of this item, unique to its containing Project.

String contextKey

The key of this document's context document, if applicable.

ItemIdentifier contextItemId

The encapsulated Project and item keys of this document's context document, if applicable.

Map queryParams

A map of additional parameters. The most common of these is "refId", which identifies the specific reference within the context identified by contextItemId .

Properties

ItemIdentifier source

The identifier for the source of the relationship.

ItemIdentifier target

The identifier for the target of the relationship. May be null if the referenced file does not exist, in which case the location of the missing object is identified by targetPathInProject .

RelationshipType type

The relationship type. The possible values are PARENT_CHILD , LINK , or GRAPHIC .

String targetPathInProject

The project path of the object being referenced.

String refTagInfo

Retrieves the tag name or DITA class of the reference.

boolean resolved

Whether the reference is resolved, that is, the target object exists.

Properties

ItemIdentifier childKey

The identifier for the uncontextualized object.

String description

A description of the context. Usually the title of the referencing DITA map.

boolean virtualTopic

Whether the topic is a virtual topic without a single source representation, such as a virtual topic generated from a title-only topicref, or a chunked section of a monolithic source.

String contextualizedTitle

Retrieves the title of the contextualized topic.

MetadataEntry[] metadataEntries

The metadata entries set on this document. It does not contain the metadata inherited from parent maps or the containing project.

Properties

String name

The facet field value.

long count

The number of documents with this value.

Properties

String name

The name of the facet field.

FacetCount[] values

The list of values for the facet, and their counts.

Properties

String id

String label

Map metadata

Represents an HTTP request or response entity.

The contents of the entity can be accessed using the body property. If expecting JSON-encoded content, HTML, or XML content, a parsed representation of the content can be accessed using the json , html , or xml properties. If there are errors parsing the content, they are available in the parseError property.

Introduced in version 4.2.

Properties

byte [] raw

The uninterpreted bytes of the entity.

String defaultCharset

The default charset for this entity, if any.

String defaultContentType

The default content type for this entity, if any.

String body

The entity body as a string.

String text

The entity body as a string.

Document xml

The body as a parsed XML DOM structure. If parsing fails, this property will be null and any exceptions can be read from the parseError property. The DOM structure can be interrogated using normal Freemarker XML handling; see the Freemarker documentation ( https://freemarker.apache.org/docs/xgui.html for details.

Object json

The body as a parsed JSON object. This can also be done manually in Freemarker using response.body?eval ; this property is provided as a convenience. If the parsing of the JSON fails, this property will be null and any exceptions can be read from the parseError property.

Document html

The body as a DOM structure generated by the Jsoup Java library ( https://jsoup.org/ ). If the parsing of the body fails, this property will be null and any exceptions can be read from the parseError property.

String base64

The raw entity encoded as base64 string. This can be used to handle binary data, for example to store a file that includes binary data.

String dataUrl

The bytes encoded as a data URL using the appropriate default MIME type.

Exception parseError

The Java exception caused by an attempt to parse the body content when accessed via xml , html , or json .

Represents the data returned by the <td.httpRequest> tag.

The contents of the response body can be accessed using the body property. If expecting JSON-encoded content, HTML, or XML content, a parsed representation of the content can be accessed using the json , html , or xml properties. If there are errors parsing the content, they are available in the parseError property. For example:

 <@td.httpRequest url="https://example.com/data.json" var="response"/>
 <#if response.status == 200>
   <#if response.contentType?contains('/json')>
     <#assign responseStruct = response.json!''/>
   <#elseif response.contentType?contains('/html')>
     <#assign responseStruct = response.html!''/>
   <#elseif response.contentType?contains('/xml')>
     <#assign responseStruct = response.xml!''/>
   </#if>
   <#if response.parseError??>
     <b>ERROR: ${response.parseError.message?html}</b>
     <pre>${response.body?html}</pre>
   </#if>
 </#if>
 

All headers are available in the headers property. The keys for the header names are represented in all lower-case, as well as in whatever case was presented in the actual response.

Introduced in version 4.2.

Properties

Map headers

Accesses a multi-valued map containing all of the headers present in the response.

long duration

The amount of time, in milliseconds, the request took to execute.

String responseUrl

Shortcut for getHeader("location") .

String contentType

Shortcut for getHeader("content-type")

int status

The HTTP status code of the response.

String statusText

The status message of the response.

byte [] raw

The uninterpreted bytes of the entity.

String defaultCharset

The default charset for this entity, if any.

String defaultContentType

The default content type for this entity, if any.

String body

The entity body as a string.

String text

The entity body as a string.

Document xml

The body as a parsed XML DOM structure. If parsing fails, this property will be null and any exceptions can be read from the parseError property. The DOM structure can be interrogated using normal Freemarker XML handling; see the Freemarker documentation ( https://freemarker.apache.org/docs/xgui.html for details.

Object json

The body as a parsed JSON object. This can also be done manually in Freemarker using response.body?eval ; this property is provided as a convenience. If the parsing of the JSON fails, this property will be null and any exceptions can be read from the parseError property.

Document html

The body as a DOM structure generated by the Jsoup Java library ( https://jsoup.org/ ). If the parsing of the body fails, this property will be null and any exceptions can be read from the parseError property.

String base64

The raw entity encoded as base64 string. This can be used to handle binary data, for example to store a file that includes binary data.

String dataUrl

The bytes encoded as a data URL using the appropriate default MIME type.

Exception parseError

The Java exception caused by an attempt to parse the body content when accessed via xml , html , or json .

Methods

String[] getHeaderValues( String name)

Retrieves all values for the header with the given name.

String getHeader( String name)

Utility method for retrieving the first value of a header.

Properties

ItemIdentifier itemIdentifier

The ItemIdentifier for the item.

ItemProperties properties

Properties and metadata for the item.

ProjectInfo projectInfo

Information about the project containing the item.

Map propertyMap

Shortcut to properties.propertyMap

Map metadataMap

The MetadataEntries as a Map.

ContentRelationship[] outgoingRelationships

The outgoing relationships, such as links and graphics, from this object.

ContentRelationship[] incomingRelationships

The incoming relationships, such as links and graphics, to this object.

ProjectMetadata projectMetadata

The metadata collection on the project containing the item.

Properties

String projectKey

The key of the Project that contains the file.

String itemKey

The key of the file, unique to the Project.

Properties

ItemIdentifier item

The encapsulated Project key and Item key for this item.

SpecifiedItemDetails specifiedDetails

The details that can be on this item in the admin application, such as name and description. Only available if this is a non-parsable binary file.

Map embeddedMetadata

The embedded metadata from the file. This will be present for PDF, Microsoft Office, several graphics formats, and a number of other file types.

String effectiveUrlPath

The URL path by which this document can be directly addressed as a standalone document.

Map propertyMap

A hash of properties set on this document. Keys common to all files are:

• key - The key of the document
• name - The name of the document
• projectKey - The key of the Project containing this document
• size - The size of the document, in bytes
• contentType - The MIME Type of the document
• path - The path to this document within the Project
• createDate - The date the document was created in Titania Delivery
• lastModified - The date the document was last modified in Titania Delivery

Keys set on image files only are:

• img_width - The width of the image, in pixels
• img_height - The height of the image, in pixels

Keys set on XML files only are:

• xml_isWellFormed
• xml_hasDTD
• xml_hasSchema
• xml_hasDoctype
• xml_doctypeExists
• xml_isValid
• xml_elementCount
• xml_elementIds
• xml_primarySchema
• xml_publicId
• xml_systemId
• xml_schemas
• xml_rootElement
• xml_rootNamespace
• xml_doctypeFile
• xml_doctypeProject
• xml_doctypeName
• xml_title
• dita_navtitle
• xml_validationError
• xml_isDita
• dita_isTopic
• dita_isMap
• dita_isDitabase
• dita_domains

Date createDate

The date that this item was created in Titania Delivery.

MetadataEntry[] metadataEntries

The metadata entries set on this document. It does not contain the metadata inherited from parent maps or the containing project.

FragmentMetadata[] allFragmentMetadata

Get all fragment metadata as a list.

Enumeration constants

ORIGINAL

The original content item.

PROCESSED

The content item processed according to its content type.

FLATTENED

For DITA topics, the processed topic with external references resolved.

MONOLITH

For DITA maps, expanded map with all referenced content resolved.

PREVIEW

A browser-friendly representation of the content item.

Properties

String name

The name of this metadata.

Object[] value

An array of Strings that are the values to this metadata

Properties

MatchMode matchMode

Possible values are ANY and ALL . ANY will match documents that contain any of the values on the filter. ALL will match documents that contain all of the values on the filter.

boolean matchAbsent

If true , this metadata filter will match documents missing the given filter.

String name

The name of this metadata.

Object[] value

An array of Strings that are the values to this metadata

Introduced in version 4.1.

Properties

String key

The unique key.

String portalKey

The key of the portal where the package was generated.

String packager

The name of the packager that created the package.

String createdBy

The ID of the authenticated user who built the package.

OfflinePackageDocumentInfo[] documents

The documents that were included in the package.

Map params

The parameters passed to the packager.

Status status

The current status of the package. Values are QUEUED, WORKING, FINISHED, and FAILED.

String scriptOutput

The output log of the packager script.

String filename

The filename used for the package.

String mimeType

The MIME type of the package.

boolean signContents

Whether to generate SHA-512/RSA signatures for each file in the package, as well as the package itself. The default is false . Introduced in version 4.2.

String signaturePathPrefix

If signing package contents, this specifies the path prefix to apply for signature files. this can be used to place signature files in their own folder in the archive. The default is no prefix. Introduced in version 4.2.

String signaturePathSuffix

If signing package contents, this specifies the suffix to add to signature files. The default is ".signature". Introduced in version 4.2.

String signatureAlgorithm

The signing algorithm to use for both the package itself and individual files within the package, if signContents is enabled. The value must match those available in Java; see https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#Signature . The default is "SHA512withRSA" . Introduced in version 4.2.

Date createDate

The timestamp when the package was requested.

String statusMessage

The current status message for the package. The package script can update this message as it builds the package in real-time, so this message should reflect the current state of the packaging process.

String hash

The hexadecimal-encoded SHA-512 hash of the package archive. Introduced in version 4.2.

String signature

The hexadecimal-encoded SHA-512/RSA checksum for the zip itself. Introduced in version 4.2.

boolean makeXmlSignatures

Whether to make XML signatures.

Introduced in version 4.1.

Properties

String projectKey

The project key.

String itemKey

The item key.

String contextKey

The context key.

String refId

The reference ID within the context, for example, the topicref ID in a DITA map.

boolean rootDoc

Whether or not this document was explicitly requested for inclusion in the package, and not included by virtue of being part of another explicit document. For example, when packaging a specific DITA map, the map itself will be marked as explicitly requested, while its topics will not (assuming the package requested the inclusion of contextualized children).

boolean virtualTopic

If true, this is a 'virtual' topic generated through content processing. There are two main cases for virtual content: DITA topics generated for <topicref> elements that specify a title but no content, and chunked sections of non-DITA XML documents.

Properties

String name

The internal name of the portal, for admin purposes.

String urlPath

The URL path of the portal.

Date createDate

The date this Portal was created.

String displayName

The name to use when displaying the Portal title through the Portal Theme.

String description

The Description of the Portal.

MetadataFilter[] metadataFilters

The Metadata Filters set on this Portal.

String ownerName

The name of this Portal's Owner.

PortalSearchFacet[] searchFacets

The search facets set on this Portal.

String commentManagerSiteKey

The unique identifier that associates comments with this Portal.

String themeName

The name of the Portal Theme associated with this Portal.

String[] enabledFeatures

The features enabled for this portal. Possible values are:

• anonymousAccess
• docLevelComments
• elLevelComments
• customAssemblies
• helpfulVote

Map parameters

Parameters for this portal as specified in the config.xml for the portal theme

String userFilterFunction

Javascript function used for user filters

PortalRobotsTxtBehavior robotsTxtBehavior

The behavior of this portal in robots.txt. One of NONE, DISALLOW, or ALLOW.

String portalProject

The key of the project for portal-generated content. Introduced in version 4.2.

Methods

boolean hasFeature( String id)

Utility method for determining whether the portal has the specified feature. Equivalent to portal.features?seq_contains(id) .

String facetDisplayName( String facetMdName)

Utility method for determining the display name of the given search facet.

Properties

String metadataName

The name of the metadata item.

String displayName

The display name of the metadata item, as set in the Search Facets tab in the admin application.

This object is only available to the Portal if the Portal has security ( hasSecurity ) enabled and the current user is logged in ( isAuthenticated ). If those two conditions fail, this object will be null and any attempt to reference it will result in a Freemarker error. This can be using the following code:

 <#if hasSecurity && isAuthenticated>
   <#-- Can now safely reference ${user} -->
 </#if>
 

or:

 <#if user??>
   <#-- Can now safely reference ${user} -->
 </#if>
 

Properties

String id

A persistent, obfuscated character string based on login name, which identifies the current user.

String userName

The username of the user, as specified by the server pointed to in this Portal's security configuration.

Map properties

The user properties pulled from the authentication service. For SAML-secured and OpenID-secured portals, this will contain whatever attributes were included in the authentication response message sent by the Identity Provider. For LDAP-secured portals, this will contain the properties listed in the LDAP connection configuration. NOTE: This collection allows for multi-valued properties, so values are arrays, not single values. Properties with single values will be lists of size 1.

Methods

boolean hasProperty( String name, String value)

Tests whether there exists a property with the given name containing the given value. If the value is not specified, this method tests whether the property exists.

Properties

String key

The project key.

String name

The project name.

String urlSlug

The project URL slug.

String fileUrlFormula

The template for generating file URLs in this project.

Date createDate

The date and time that a project was created.

String contentPortal

The key of the portal for which this project holds content. Introduced in version 4.2.

Properties

String parentKey

The parent key for the item. Will be null for root-level items.

String key

The object's unique key that can be used to retrieve it directly from the project.

String label

The label of this object.

String contentType

The content type of the object. Will be null for folders.

String projectPath

The path within the project to this object. The path will begin with a forward slash (/) and be delimited by forward slashes. The path will end in a forward slash if this is a folder.

boolean folder

Whether the object is a folder.

long size

The size, in bytes, of the object.

Date lastModified

The last-modified date of the object.

Date createDate

The creation date of the object.

Properties

String projectKey

The project key.

MetadataEntry[] metadataEntries

The metadata entries set on project.

Properties

String projectKey

The key of this document's containing Project.

String itemKey

This document's item Key, unique to the project. In some cases, may be of the form key:elementId for chunked content.

String path

The path to this document within its project.

String filename

This document's filename.

String urlPath

The URL path for this file.

String title

This document's title, or its filename if the title does not exist.

String searchTitle

This document's search title, or its title if the searchTitle does not exist.

String[] keywords

The keywords of the document.

String textContents

The raw text contents of the document.

String contextKey

The key of this document's context document, or xxnullxx if it is a stand-alone document.

String contextName

The name of this document's context document.

String contextRefId

If this document is present in its parent context more than once, the contextRefId identifies which version the current document represents.

Long created

The date that this document was created in Titania Delivery.

Long lastModified

The date that this document was last modified in Titania Delivery.

boolean contextualized

true if this document is present in a parent context document. Equal to contextKey != xxnullxx .

String highlight

If this document was returned as part of a search query, this field will contain the text contents surrounding the most-relevant "hit" in the document.

Map metadata

A hash representing the metadata on this document. The keys are metadata names as assigned in the TD admin application or present in the source document. The value is an array of strings representing the values of that metadata. If a key is present it is guaranteed that there will be at least one element in the values array.

Map metadataNormalized

Similar to metadata , but with _md stripped from all the keys.

boolean virtual

Describes whether this search result represents a physical file in a Titania Delivery project, or a virtual, generated document. Examples of virtual documents include topics generated for DITA <topicref> elements that specify a title but no @href or @keyref, or a chunked section of a non-DITA document.

This object is the data type of the content array of groups. It represents a "group" of search results.

Search results are generally grouped by their DITA map context. That is, a DITA topic used in multiple DITA map contexts will have its matching search results grouped together. No other documents are grouped in this way.

nContexts will always be >= 1 and equal to results?size . firstResult will be the same SearchResultDocument as results[0] .

Properties

SearchResultDocument firstResult

convenience variable for results[0] .

String groupingValue

The value of the grouping field specified by the query for all of the documents in this group. For example, grouped search results are grouped by the "itemKey" property by default, so this value will be the itemKey of all of the results in this group. When grouping by another field, this will be the value for that field on all of the documents in this group. Introduced in version 4.2.1.

int nContexts

The size of the results array. The value will always be >= 1.

SearchResultDocument[] results

The search results grouped by topic. If the topic was returned by a search result, then each context in which it exists will be present in the array. If the document is stand-alone, (that is, it is not referenced by any parent document) then there will be only one entry in the array. results?size will always be equal to nContexts .

Properties

FacetField[] facetFields

The list of facet counts for the search.

int number

The zero-based index of the current page.

int size

The maximum number of results this page could contain.

int totalPages

The total number of pages available for the current search.

int numberOfElements

The number of elements on the current page. Will be less than or equal to size .

long totalElements

The total number of elements (groups or documents) returnable by the current search.

long totalHits

The total number of documents returnable by the current search.

boolean previousPage

true if there is a previous page.

boolean previous

true if there is a previous page.

boolean firstPage

true if the current page is the first page.

boolean nextPage

true if there is a next page.

boolean next

true if there is a next page.

boolean lastPage

true if the current page is the last page.

boolean last

true if the current page is the last page.

String groupedBy

The property by which the results are grouped when applicable, such as the default search page or the results of the td.groupSearch directive. The default grouping field is "itemKey", meaning that DITA topics with multiple DITA map contexts will be grouped together. This value will be null for ungrouped searches. Introduced in version 4.2.1.

Object[] startNextAfter

Markers that can be used in a subsequent request to get the next page of results. Avoids performance and/or hard limits on the full size of all pages in the search engine.

T[] content

The contents of the current page. This will either be SearchResultGroup or SearchResultDocument objects, depending on the way the query was performed.

• When the search is performed using the standard portal search page, and rendered with searchResults.ftl , this will be a list of SearchResultGroup .
• When performed using the <@td.groupSearch> tag, the results will also be of type SearchResultGroup .
• When performed using <@td.search> , the results will be lists of SearchResultDocument .

An extension of UserDataStorage that is shared by all users of a portal, including anonymous users. This object exposes a number of special methods for storing data and documents in a searchable way.

Portals have an associated content project that can store documents and metadata generated by the portal. Also, each portal can have one or more searchable indexes containing arbitrary data. (Additional portal data storage capabilities for nonindexed values, counters, and lists are described under "DataStorage".)

When a portal is created, a project is automatically created and associated with the portal as the portal content project. This project may contain portal-generated content, and functions like any other content project. The siteData object provides methods for accessing portal content items.

Indexed data can be stored and searched under user-defined index names. Each index should hold similarly structured records. Methods for storing and retrieving indexed data are provided in Freemarker and javascript using the siteData object. The administration interface also provides access to view and download portal indexed data. IMPORTANT: The total number of user-defined indices on the platform cannot exceed 100 at any time (across all portals). Theme developers and platform administrators should ensure that no more than 100 indices exist at any time.

Introduced in version 4.2.

Methods

Iterable searchIndexed( String index, String query, int [] paging)

Searches the given index using the given search. Since each index can have its own record type, all indexed searches are ordered by the built-in Elasticsearch field, "_doc".

int deleteIndexed( String index, String query)

Deletes records from the given index that match the given query.

int deleteIndexed( String index, String query, boolean waitRefresh)

Deletes records from the given index that match the given query. Passing false for the waitRefresh method will cause the method to return before the deletion has been fully processed. The default is true

void deleteIndex( String index)

Deletes the index with the given name, and all data in it.

void putIndexed( String index, Object value)

Stores a data structure in such a way that its properties can be queried using normal search syntax. The index functions as a namespace for the stored data. As a best practice, radically different data structures should be stored in different indexes.

boolean putIndexed( String index, Object value, boolean waitRefresh)

Stores a data structure in such a way that its properties can be queried using normal search syntax. The index functions as a namespace for the stored data. As a best practice, radically different data structures should be stored in different indexes. Passing false for the waitRefresh method will cause the method to return before the insertion has been fully processed. The default is true

void putFile( String location, String mimeType, CharSequence contents, Map metadata)

Creates or updates a file in the portal's project. If the file already exists, its contents will be overwritten and its metadata replaced with the given hash.

boolean fileExists( String location)

Determines whether a file exists at the given path.

String getFile( String location, String representation)

Retrieve the contents of the file at the given path as a string.

String getFileLocator( String location)

Retrieves the File Locator for the file at the given path.

String getFileDownloadURL( String location, String representation)

Gets an HTTP URL at which the given file can be downloaded directly, optional with a processed representation.

String getFileUploadURL( String location, boolean folderMode, String itemName)

Get a URL to add or replace a file via POST. Any existing file at the location will be overwritten.

boolean deleteFile( String location)

Deletes the given file or folder.

boolean setFileMetadata( String location, Map metadata)

Sets the metadata on the given file. The existing non-intrinsic metadata entries for the file will be replaced with those supplied. Use updateFileMetadata(String,Map) for adding additional metadata to a file.

boolean updateFileMetadata( String location, Map metadata)

Updates the metadata on the given file. The existing non-intrinsic metadata entries for the file will be updated and merged with those supplied.

String getProcessingPhase( String location)

Gets the current processing phase of the item at the specified location.

ProjectItem[] getProjectRoots()

List the portal project root contents.

ProjectItem[] getFolderContents( String location)

List the specified folder contents.

boolean exists( String key)

Determines if data with the given key exists.

void put( String dataKey, Object data)

Stores data with a key. If the data is a string, it is stored as-is. Otherwise, it is converted to JSON and then stored.

Object get( String dataKey)

Retrieves the data with the given key. Objects are encoded as JSON for storage, so the resulting object will be whatever type was stored, unless it's an object, in which case it will be represented as a map hierarchy.

void push( String listKey, Object value, int cap)

Pushes a new value onto the list with the given key.

void pushUnique( String listKey, Object value, int cap)

Pushes a new value onto the list with the given key. If it already exists in the list, it is removed and moved to the top.

Object[] getList( String listKey)

Retrieves the list with the given key.

boolean existsInList( String listKey, Object value)

Determines whether the given value exists in the list with the given key.

void removeFromList( String listKey, Object value)

Removes the given value from the list with the given key.

long getCounter( String key)

Retrieves the counter with the given key.

void setCounter( String key, long counter)

Assigns a counter value to the given key.

void incrementCounter( String key, long by)

Increments the counter with the given key by the given amount (which may be negative). If no such counter exists, it will be created and set to the given increment value.

void delete( String key)

Deletes the data and/or list with the given key.

void deleteCategory( String category)

Deletes all entries in the given category.

Map getCategory( String category)

Retrieves all entries in a given category.

Properties

String title

The title of the document, as specified in the administrative application.

String description

The description of the document, as specified in the administrative application.

String[] keywords

The keywords of the document, as specified in the administrative application.

Portals can store data on the server for later retrieval. If the user is authenticated, the stored data is persisted between sessions. Otherwise, it expires when the client session expires.

There are three types of nonindexed persistent data: values, counters, and lists. Each is associated with a key. A key may have all three types of values.

Values

Values are stored via put(String, Object) and retrieved via get(String). Values can be anything that can be serialized as JSON, including strings, numbers, booleans, lists, and data structures. Data values are serialized as JSON when stored in the database, and de-serialized when retrieved. If a value is a complex non-map object when it is stored, it will be retrieved as a map.

Lists

Lists are essentially managed arrays that can be added to or removed from without needing to retrieve the full data structure. You create/add to lists via push(String, Object, int) or pushUnique(String, Object, int). The full list can be retrieved via getList(String). Elements can be removed via removeFromList(String, Object). You can check whether a value exists in a list via existsInList(key). Like values, list entries can be anything that can be serialized as JSON.

Counters

Counters are whole number values that can be easily incremented and decremented with the atomic operation incrementCounter(String, long). They can also be retrieved and stored via getCounter() and setCounter().

Important: The three values are treated independently. If you set a value via setCounter(), it must be retrieved by getCounter(); it will not be retrieved by get(). Similarly, lists stored with put() cannot be modified via push(). However, if a given key has more than one type of value - a list and a counter, for instance - calling delete() on that key will delete all the associated data.

Categories

A category is implicitly defined by keys beginning with a certain prefix and a period. For example, deleteCategory('foo') would delete any entry with a key beginning with 'foo.' ('foo.a', 'foo.b', etc.). It would not delete 'foo'. There are a number of methods that allow the interaction with whole groups of entries by their category. This allows the development of features that involve an interaction of multiple keys such that they can be deleted.

Introduced in version 4.0.

Methods

boolean exists( String key)

Determines if data with the given key exists.

void put( String dataKey, Object data)

Stores data with a key. If the data is a string, it is stored as-is. Otherwise, it is converted to JSON and then stored.

Object get( String dataKey)

Retrieves the data with the given key. Objects are encoded as JSON for storage, so the resulting object will be whatever type was stored, unless it's an object, in which case it will be represented as a map hierarchy.

void push( String listKey, Object value, int cap)

Pushes a new value onto the list with the given key.

void pushUnique( String listKey, Object value, int cap)

Pushes a new value onto the list with the given key. If it already exists in the list, it is removed and moved to the top.

Object[] getList( String listKey)

Retrieves the list with the given key.

boolean existsInList( String listKey, Object value)

Determines whether the given value exists in the list with the given key.

void removeFromList( String listKey, Object value)

Removes the given value from the list with the given key.

long getCounter( String key)

Retrieves the counter with the given key.

void setCounter( String key, long counter)

Assigns a counter value to the given key.

void incrementCounter( String key, long by)

Increments the counter with the given key by the given amount (which may be negative). If no such counter exists, it will be created and set to the given increment value.

void delete( String key)

Deletes the data and/or list with the given key.

void deleteCategory( String category)

Deletes all entries in the given category.

Map getCategory( String category)

Retrieves all entries in a given category.

This tag contains the following attributes:

limit

The maximum number of results per page. Must be a positive integer n where 0 < n <= 2147483647. This does not limit the total number of search results, which may be limited by other settings.

• Required: false
• Type: int
• Default: 10

scope

The scope of the @var attribute. Valid values are "page" and "request".

• Required: false
• Type: String
• Default: "request"

sortBy

The property or properties to sort by, separated by whitespace or comma.

• Required: false
• Type: String
• Default: none

sortDirection

A list of sort directions ('ASC' or 'DESC'), corresponding in order to the list of 'sortBy' fields. If the list is empty or shorter than the 'sortBy' list, the default of 'ASC' will be used for the missing directions.

• Required: false
• Type: String
• Default: ASC

startAfter

Alternative pagination mode. The startNextAfter token from a previous page.

• Required: false
• Type: Object
• Default: null

startPage

The page number to return. Must be an integer 0 <= n <= 10000. Note that ithe preferred pagination method is to use the startAfter attribute.

• Required: false
• Type: int
• Default: 0

var

The name of the variable used to access the result.

• Required: true
• Type: String
• Default: none

This tag contains the following attributes:

assembly

The Assembly object to open in the editor. If not specified, the editor will be opened with a new empty assembly.

• Required: false
• Type: Assembly
• Default: none

scope

The scope of the @var attribute. Valid values are "page" and "request".

• Required: false
• Type: String
• Default: "request"

urlQuery

The query string. This value will NOT be URL-encoded, so it should be encoded already. You can also use nested <@td.urlParam> tags to specify individual URL parameters in a URL-escaped way.

• Required: false
• Type: String
• Default: none

var

The name of the variable used to access the result.

• Required: false
• Type: String
• Default: none

This tag contains the following attributes:

assembly

The Assembly object.

• Required: true
• Type: Assembly
• Default: none

refId

The ID of the node in the Assembly to display. If omitted, the URL of the Assembly itself is returned.

• Required: false
• Type: String
• Default: The root node of the Assembly

scope

The scope of the @var attribute. Valid values are "page" and "request".

• Required: false
• Type: String
• Default: "request"

urlQuery

The query string. This value will NOT be URL-encoded, so it should be encoded already. You can also use nested <@td.urlParam> tags to specify individual URL parameters in a URL-escaped way.

• Required: false
• Type: String
• Default: none

var

The name of the variable used to access the result.

• Required: false
• Type: String
• Default: none

This tag contains the following attributes:

addPageviewImage

Whether to automatically insert an HTML <img> tag after the rendered content that will request a 1x1-pixel, invisible image causing the server to record a view of this content. This will force a pageview to be recorded, even if the rendered page is served from a browser or other cache.

• Required: false
• Type: Boolean
• Default: false
• Since: 4.2

assembly

An Assembly whose content to render. One of this, 'url', or 'searchTerm' must be specified, and they are evaluated in that order.

• Required: false
• Type: Assembly
• Default: None

assemblyTopicRef

If an assembly is specified, this is the ID of the topic within that assembly to render. If an assembly is specified without this attribute, the assembly map itself is rendered. this is specified without an assembly, it is ignored.

• Required: false
• Type: String
• Default: None

contextKey

The context key. Overridden by contextUrl and/or contextUrlString and/or the context key specified in url/urlString, in that order.

• Required: false
• Type: String
• Default: none

contextUrl

The ContentLocator of the context from which to load the data. Used to configure hyperlinks and image references in the resulting content.

• Required: false
• Type: ContentLocator
• Default: none

contextUrlString

The ContentLocator of the context from which to load the data. Used to configure hyperlinks and image references in the resulting content.

• Required: false
• Type: String
• Default: none

expandReferences

Whether to expand references to child documents. This is used to render all topics in a DITA Map-based publication on a single page.

• Required: false
• Type: boolean
• Default: false

ignoreCache

Whether to go to the database, ignoring caches. Note that this will flush the requested data from the cache and re-cache the newly loaded version. Default is false.

• Required: false
• Type: boolean
• Default: none

itemKey

The item key. Overridden by url and/or urlString.

• Required: false
• Type: String
• Default: none

linkContext

This attribute is deprecated and can be ignored.

• Required: false
• Type: Boolean
• Default: none

pipeline

Post-transform content processing can be accomplished with built-in content processing pipelines. Currently the only supported pipeline is "filterchain:/harp/portal/markFilteredTopics.xml", which can mark or remove links to topics not available in the portal, and requires pipelineParameters "portal" (PortalIdentity), "contextKey" (ItemIdentifier), and "removeFilteredEntries", a boolean controlling whether to remove or simply mark links to filtered content.

• Required: false
• Type: String
• Default: None

projectKey

The Project key. Overridden by url and/or urlString.

• Required: false
• Type: String
• Default: none

recordPageview

Whether to record a pageview for the given content in the reporting system. This should only be true when viewing content in a custom portal page. The built-in content viewing pages all record the pageview before the response is rendered. But when rendering content on a custom portal page, this should be specified as true to ensure that the content view is recorded.

• Required: false
• Type: boolean
• Default: false

searchTerm

A search term whose first result will be the SearchResultDocument rendered by this tag. Overrides url and contextUrl attributes. Required if url attribute not provided. Can be combined with metadata specified in metadataFilterTags.

• Required: false
• Type: String
• Default: none

timeout

The amount of time, in ms, after which the transform may be cancelled. The default value is generally 60000 (60 seconds), though this can vary depending on the application's configuration. Set to 0 to disable timeouts, but do this with care; infinitely-running transforms can severely degrade application performance site-wide.

• Required: false
• Type: long
• Default: 60000
• Since: 4.2

url

The ContentLocator object describing the content to retrieve. Required if searchTerm attribute is not provided.

• Required: false
• Type: ContentLocator
• Default: none

urlString

The ContentLocator object describing the content to retrieve. Required if searchTerm attribute is not provided.

• Required: false
• Type: String
• Default: none

xsl

Relative path to an XSLT file, relative to the WEB-INF directory of the web application, to apply to the content. Parameters to the XSLT can be passed using nested xslParam tags.

• Required: false
• Type: String
• Default: none

Rendering a DITA Map as One Page

The expandReferences attribute can be used when referencing DITA maps to insert an XML document containing all of the topics in the publication, instead of the flattened DITA map markup. The XML structure for this document is similar, but not quite the same, as the structure used by the DITA Open Toolkit when rendering PDF output.

• The root element is the map's root element.
• The first child of the root element is <opentopic:map xmlns:opentopic="http://www.idiominc.com/opentopic">.
  • This structure contains the original, unexpanded map structure, including the map title element.
  • On each topicref, the ID of the corresponding topic element is in the puckdita:cxt-topicId attribute (xmlns:puckdita="http://www.titaniasoftware.com/namespace/puck-saxfilter-dita").
  • The metadata, including navtitle, for each topicref will have been resolved.
• After the <opentopic:map> element, all of the topics referenced by the map flow, nested as specified by the map. Navtitle-only topicrefs are rendered as topics with the appropriate title. The id attribute maps to the puckdita:cxt-topicId attribute for its topicref in the <opentopic:map> section.
• The @href attribute on all scope="local" format="dita" links and cross-references will have already been converted into IDREF-style links (e.g. href="#targetId") that will resolve in the flattened document.
• Related links, including those generated from reltables and the map structure, will be included in the topics. To avoid displaying them they must be excluded by the stylesheet. You can differentiate authored links from generated links using the puckdita:linkSource attribute. If the attribute is not present, then the link was manually authored. Otherwise:

  "structure"

  The link is derived from the map structure.

  "reltable"

  The link was generated from a reltable.

This tag contains the following attributes:

harpUrl

The ContentLocator. If specified, projectKey and itemKey are ignored.

• Required: false
• Type: ContentLocator
• Default: none

harpUrlString

The ContentLocator as a string. If specified, projectKey and itemKey are ignored.

• Required: false
• Type: String
• Default: none

itemKey

The item key

• Required: false
• Type: String
• Default: none

projectKey

The Project key

• Required: false
• Type: String
• Default: none

scope

The scope of the @var attribute. Valid values are "page" and "request".

• Required: false
• Type: String
• Default: "request"

searchResult

The SearchResultDocument object. If specified, projectKey, portalKey, and harpUrl are ignored.

• Required: false
• Type: SearchResultDocument
• Default: none

var

The name of the variable used to access the result.

• Required: true
• Type: String
• Default: none

This tag contains the following attributes:

cacheKey

Unique identifier for this tag. If specified and cacheSecs is positive, this will serve as the cache key. Otherwise the relevant attributes will be used and all tags with the same attribute values will share the cache.

• Required: false
• Type: String
• Default: none

cacheSecs

The number of seconds to cache the results. All calls to this tag with the same attributes will receive the cached value for the specified length of time unless the cacheKey attribute is specified, in which case only tags with the same ID will be affected by the caching. Specify 0 or a negative number to disable caching.

• Required: false
• Type: int
• Default: 0

createdBefore

A Date value specifying the last creation date for the search. Only files created since the given date will be returned. Values must be java.util.Date objects. Dates can be converted to Strings in Freemarker templates using the ?date, ?datetime, and ?time built-ins for Strings. See http://freemarker.org/docs/ref_builtins_string.html#ref_builtin_string_date for details.

• Required: false
• Type: Date
• Default: none

createdSince

A Date value specifying the earliest creation date for the search. Only files created since the given date will be returned. Values must be java.util.Date objects. Dates can be converted to Strings in Freemarker templates using the ?date, ?datetime, and ?time built-ins for Strings. See http://freemarker.org/docs/ref_builtins_string.html#ref_builtin_string_date for details.

• Required: false
• Type: Date
• Default: none

createdSinceDays

Only return results created in the preceding number of days specified by this attribute.

• Required: false
• Type: int
• Default: none

escape

Whether to escape characters in the query so that it operates as a true full-text search rather than a more formal search engine query. When set to 'true', colons, parentheses, and other special characters used to structure queries will be escaped and treated as plain text. If false, the query will be treated as a formal search engine query, and syntax errors will cause failures. The default is false.

• Required: false
• Type: String
• Default: false
• Since: 4.2

facets

A space separated list of search facets. Facets do not affect search results.

• Required: false
• Type: Object
• Default: null
• Since: 4.2

filter

A search query to be used as a search filter. The search filter is applied as a secondary search on primary search results.

• Required: false
• Type: String
• Default: null
• Since: 4.2

groupBy

The property to group results by. This can either be a base property of SearchResultDocument or a metadata field. If a metadata field, the name should end in "_md". For instance, to group by "product" metadata, specify "product_md". The default value is "itemKey", meaning that different uses of the same DITA topic in different DITA maps will be grouped together.

• Required: false
• Type: String
• Default: "itemKey"
• Since: 4.2.1

highlightSize

The total number of characters before and after the given search term in a result. Note that if the search term is "*" then the highlight size will be 0. Must be an integer n 0 <= n <= 2147483647.

• Required: false
• Type: int
• Default: 300

limit

The maximum number of results per page. Must be a positive integer n where 0 < n <= 2147483647. This does not limit the total number of search results, which may be limited by other settings.

• Required: false
• Type: int
• Default: 10

maxFacetValues

The maximum number of facet values to return when executing the search. The resulting facets will be listed from most-hits to least-hits. Note that this can have a significant impact on search performance.

• Required: false
• Type: int
• Default: 10

metadataFields

Space-separated list of metadata fields to return with each search result. If the list is empty, all default metadata fields will be returned. Otherwise, only the listed fields will be returned. An asterisk ("*") may be used in any term as a wildcard. Use just "*" to return all metadata fields (both default and custom).

• Required: false
• Type: String
• Default: null

modifiedBefore

A Date value specifying the last modified date for the search. Only files modified since the given date will be returned. Values must be java.util.Date objects. Dates can be converted to Strings in Freemarker templates using the ?date, ?datetime, and ?time built-ins for Strings. See http://freemarker.org/docs/ref_builtins_string.html#ref_builtin_string_date for details.

• Required: false
• Type: Date
• Default: none

modifiedSince

A Date value specifying the earliest modified date for the search. Only files modified since the given date will be returned. Values must be java.util.Date objects. Dates can be converted to Strings in Freemarker templates using the ?date, ?datetime, and ?time built-ins for Strings. See http://freemarker.org/docs/ref_builtins_string.html#ref_builtin_string_date for details.

• Required: false
• Type: Date
• Default: none

modifiedSinceDays

Only return results modified in the preceding number of days specified by this attribute.

• Required: false
• Type: int
• Default: none

portalContent

Whether and how to include portal content in search. Valid values are "exclude", "include", and "only".

• Required: false
• Type: String
• Default: exclude
• Since: 4.2

query

The search query. Must not be the empty string ("").

• Required: false
• Type: String
• Default: *

resultsPerGroup

The maximum number of "contexts" to return per group.

• Required: false
• Type: int
• Default: 5

scope

The scope of the @var attribute. Valid values are "page" and "request".

• Required: false
• Type: String
• Default: "request"

sortBy

The property or properties to sort by, separated by whitespace or comma.

• Required: false
• Type: String
• Default: none

sortDirection

A list of sort directions ('ASC' or 'DESC'), corresponding in order to the list of 'sortBy' fields. If the list is empty or shorter than the 'sortBy' list, the default of 'ASC' will be used for the missing directions.

• Required: false
• Type: String
• Default: ASC

startAfter

Alternative pagination mode. The startNextAfter token from a previous page.

• Required: false
• Type: Object
• Default: null

startPage

The page number to return. Must be an integer 0 <= n <= 10000. Note that ithe preferred pagination method is to use the startAfter attribute.

• Required: false
• Type: int
• Default: 0

var

The name of the variable used to access the result.

• Required: true
• Type: String
• Default: none

This tag contains the following attributes:

contentType

The request body content type. (Equivalent to setting "Content-Type" header.)

• Required: false
• Type: String
• Default: If sending a file, the content type of the file. Otherwise, none.

contextId

Context ID to preserve request context, such as cookies and authentication status, across several requests.

• Required: false
• Type: String
• Default: none

contextScope

The scope, for the context identified by the contextId to be retained. Possible values are "session" (the default), in which case the context persists for the duration of the user's HTTP session; "request", in which case the context expires at the end of the current (Titania Delivery) request; or "global", in which case the context is shared by all Titania Delivery users.

• Required: false
• Type: String
• Default: session

defaultCharset

The default character set to use when interpreting the request entity, unless otherwise specified by the Content-Type header.

• Required: false
• Type: String
• Default: UTF-8

followRedirects

Maximum number of redirects to follow. Negative means unlimited.

• Required: false
• Type: int
• Default: -1

headers

The HTTP headers to set on the request.

• Required: false
• Type: Map
• Default: none

itemKey

If sending the contents of a file, the item key of the file.

• Required: false
• Type: String
• Default: None

method

The HTTP request method.

• Required: false
• Type: String
• Default: GET

parameters

Additional parameters to set on the request. If the method is POST and there is no tag body, the parameters will be put into an application/x-www-form-urlencoded request entity. Otherwise, the parameters will be added to the request URL.

• Required: false
• Type: Map
• Default: none

password

Password for HTTP authentication.

• Required: false
• Type: String
• Default: none

projectKey

If sending the contents of a file, the project key of the file.

• Required: false
• Type: String
• Default: None

rendition

If sending the contents of a file, the ItemRepresentationType of the rendition to send.

• Required: false
• Type: String
• Default: ORIGINAL

scope

The scope of the @var attribute. Valid values are "page" and "request".

• Required: false
• Type: String
• Default: "request"

timeout

Timeout value in seconds.

• Required: false
• Type: int
• Default: 20

url

The URL to request.

• Required: true
• Type: String
• Default: none

username

User name for HTTP authentication.

• Required: false
• Type: String
• Default: none

var

The name of the variable used to access the result.

• Required: false
• Type: String
• Default: none

writeResponse

Whether to write response body to tag output.

• Required: false
• Type: boolean
• Default: false

This tag has no attributes.

Markdown is a tool that can convert text to HTML but that uses a much simpler and more human-readable syntax than HTML.

This tag contains the following attributes:

metadataName

The name of the filter

• Required: true
• Type: String
• Default: none

metadataValue

The value of the filter

• Required: true
• Type: String
• Default: none

This tag contains the following attributes:

page

The path to the custom page, relative to the /pages/custom folder in the portal theme.

• Required: true
• Type: String
• Default: none

scope

The scope of the @var attribute. Valid values are "page" and "request".

• Required: false
• Type: String
• Default: "request"

urlQuery

The query string. This value will NOT be URL-encoded, so it should be encoded already. You can also use nested <@td.urlParam> tags to specify individual URL parameters in a URL-escaped way.

• Required: false
• Type: String
• Default: none

var

The name of the variable used to access the result.

• Required: false
• Type: String
• Default: none

This tag contains the following attributes:

name

The parameter name.

• Required: true
• Type: String
• Default: none

value

The parameter value.

• Required: true
• Type: Object
• Default: none

This tag contains the following attributes:

scope

The scope of the @var attribute. Valid values are "page" and "request".

• Required: false
• Type: String
• Default: "request"

urlQuery

The query string. This value will NOT be URL-encoded, so it should be encoded already. You can also use nested <@td.urlParam> tags to specify individual URL parameters in a URL-escaped way.

• Required: false
• Type: String
• Default: none

value

The path within the Portal UI. If omitted, the Portal homepage URL will be used.

• Required: false
• Type: String
• Default: The url to the Portal home page.

var

The name of the variable used to access the result.

• Required: false
• Type: String
• Default: none

This tag contains the following attributes:

contextKey

The context key. Overridden by contextUrl and/or contextUrlString and/or the context key specified in url/urlString, in that order.

• Required: false
• Type: String
• Default: none

contextUrl

The ContentLocator of the context from which to load the data. Used to configure hyperlinks and image references in the resulting content.

• Required: false
• Type: ContentLocator
• Default: none

contextUrlString

The ContentLocator of the context from which to load the data. Used to configure hyperlinks and image references in the resulting content.

• Required: false
• Type: String
• Default: none

itemKey

The item key. Overridden by url and/or urlString.

• Required: false
• Type: String
• Default: none

projectKey

The Project key. Overridden by url and/or urlString.

• Required: false
• Type: String
• Default: none

refId

The reference ID, in cases of a view of content in the context of another document, such as a top-level XML document or DITA map.

• Required: false
• Type: String
• Default: none

url

The ContentLocator object describing the content to retrieve. Required if searchTerm attribute is not provided.

• Required: false
• Type: ContentLocator
• Default: none

urlString

The ContentLocator object describing the content to retrieve. Required if searchTerm attribute is not provided.

• Required: false
• Type: String
• Default: none

This tag contains the following attributes:

contentType

The part content type. (Equivalent to setting "Content-Type" header.)

• Required: false
• Type: String
• Default: If sending a file, the content type of the file. Otherwise, none.

filename

The filename for this part.

• Required: false
• Type: String
• Default: If uploading a file from a project, the name of the file. Otherwise, no default.

itemKey

If sending the contents of a file, the item key of the file.

• Required: false
• Type: String
• Default: None

name

The name for this part.

• Required: false
• Type: String
• Default: file

projectKey

If sending the contents of a file, the project key of the file.

• Required: false
• Type: String
• Default: None

rendition

If sending the contents of a file, the ItemRepresentationType of the rendition to send.

• Required: false
• Type: String
• Default: ORIGINAL

This tag contains the following attributes:

cacheKey

Unique identifier for this tag. If specified and cacheSecs is positive, this will serve as the cache key. Otherwise the relevant attributes will be used and all tags with the same attribute values will share the cache.

• Required: false
• Type: String
• Default: none

cacheSecs

The number of seconds to cache the results. All calls to this tag with the same attributes will receive the cached value for the specified length of time unless the cacheKey attribute is specified, in which case only tags with the same ID will be affected by the caching. Specify 0 or a negative number to disable caching.

• Required: false
• Type: int
• Default: 0

createdBefore

A Date value specifying the last creation date for the search. Only files created since the given date will be returned. Values must be java.util.Date objects. Dates can be converted to Strings in Freemarker templates using the ?date, ?datetime, and ?time built-ins for Strings. See http://freemarker.org/docs/ref_builtins_string.html#ref_builtin_string_date for details.

• Required: false
• Type: Date
• Default: none

createdSince

A Date value specifying the earliest creation date for the search. Only files created since the given date will be returned. Values must be java.util.Date objects. Dates can be converted to Strings in Freemarker templates using the ?date, ?datetime, and ?time built-ins for Strings. See http://freemarker.org/docs/ref_builtins_string.html#ref_builtin_string_date for details.

• Required: false
• Type: Date
• Default: none

createdSinceDays

Only return results created in the preceding number of days specified by this attribute.

• Required: false
• Type: int
• Default: none

escape

Whether to escape characters in the query so that it operates as a true full-text search rather than a more formal search engine query. When set to 'true', colons, parentheses, and other special characters used to structure queries will be escaped and treated as plain text. If false, the query will be treated as a formal search engine query, and syntax errors will cause failures. The default is false.

• Required: false
• Type: String
• Default: false
• Since: 4.2

facets

A space separated list of search facets. Facets do not affect search results.

• Required: false
• Type: Object
• Default: null
• Since: 4.2

filter

A search query to be used as a search filter. The search filter is applied as a secondary search on primary search results.

• Required: false
• Type: String
• Default: null
• Since: 4.2

highlightSize

The total number of characters before and after the given search term in a result. Note that if the search term is "*", then the highlight size will be 0. Must be an integer n 0 <= n <= 2147483647.

• Required: false
• Type: int
• Default: 300

limit

The maximum number of results per page. Must be a positive integer n where 0 < n <= 2147483647. This does not limit the total number of search results, which may be limited by other settings.

• Required: false
• Type: int
• Default: 10

maxFacetValues

The maximum number of facet values to return when executing the search. The resulting facets will be listed from most-hits to least-hits. Note that this can have a significant impact on search performance.

• Required: false
• Type: int
• Default: 10

metadataFields

Space-separated list of metadata fields to return with each search result. If the list is empty, all default metadata fields will be returned. Otherwise, only the listed fields will be returned. An asterisk ("*") may be used in any term as a wildcard. Use just "*" to return all metadata fields (both default and custom).

• Required: false
• Type: String
• Default: null

modifiedBefore

A Date value specifying the last modified date for the search. Only files modified since the given date will be returned. Values must be java.util.Date objects. Dates can be converted to Strings in Freemarker templates using the ?date, ?datetime, and ?time built-ins for Strings. See http://freemarker.org/docs/ref_builtins_string.html#ref_builtin_string_date for details.

• Required: false
• Type: Date
• Default: none

modifiedSince

A Date value specifying the earliest modified date for the search. Only files modified since the given date will be returned. Values must be java.util.Date objects. Dates can be converted to Strings in Freemarker templates using the ?date, ?datetime, and ?time built-ins for Strings. See http://freemarker.org/docs/ref_builtins_string.html#ref_builtin_string_date for details.

• Required: false
• Type: Date
• Default: none

modifiedSinceDays

Only return results modified in the preceding number of days specified by this attribute.

• Required: false
• Type: int
• Default: none

portalContent

Whether and how to include portal content in search. Valid values are "exclude", "include", and "only".

• Required: false
• Type: String
• Default: exclude
• Since: 4.2

query

The search query. Must not be the empty string ("").

• Required: false
• Type: String
• Default: *

scope

The scope of the @var attribute. Valid values are "page" and "request".

• Required: false
• Type: String
• Default: "request"

sortBy

The property or properties to sort by, separated by whitespace or comma.

• Required: false
• Type: String
• Default: none

sortDirection

A list of sort directions ('ASC' or 'DESC'), corresponding in order to the list of 'sortBy' fields. If the list is empty or shorter than the 'sortBy' list, the default of 'ASC' will be used for the missing directions.

• Required: false
• Type: String
• Default: ASC

startAfter

Alternative pagination mode. The startNextAfter token from a previous page.

• Required: false
• Type: Object
• Default: null

startPage

The page number to return. Must be an integer 0 <= n <= 10000. Note that ithe preferred pagination method is to use the startAfter attribute.

• Required: false
• Type: int
• Default: 0

var

The name of the variable used to access the result.

• Required: true
• Type: String
• Default: none

The Search tag is similar in function to the <@td.searchResultUrl> tag. However, instead of generating a link to the search results page (/pages/searchResults.ftl) which renders the results of the given search parameters, this tag executes the search and places the results into a variable for use in the current page. This allows for adding search results from theme-defined parameters into any page.

This tag contains the following attributes:

query

The query.

• Required: false
• Type: String
• Default: *

scope

The scope of the @var attribute. Valid values are "page" and "request".

• Required: false
• Type: String
• Default: "request"

urlQuery

The query string. This value will NOT be URL-encoded, so it should be encoded already. You can also use nested <@td.urlParam> tags to specify individual URL parameters in a URL-escaped way.

• Required: false
• Type: String
• Default: none

var

The name of the variable used to access the result.

• Required: false
• Type: String
• Default: none

This tag contains the following attributes:

filter

The search clause for filtering content.

• Required: true
• Type: String
• Default: None

This tag contains the following attributes:

scope

The scope of the @var attribute. Valid values are "page" and "request".

• Required: false
• Type: String
• Default: "request"

urlQuery

The query string. This value will NOT be URL-encoded, so it should be encoded already. You can also use nested <@td.urlParam> tags to specify individual URL parameters in a URL-escaped way.

• Required: false
• Type: String
• Default: none

value

The path within the "static" folder.

• Required: false
• Type: String
• Default: The base URL to the "static" folder

var

The name of the variable used to access the result.

• Required: false
• Type: String
• Default: none

This tag contains the following attributes:

name

The parameter name

• Required: true
• Type: String
• Default: none

value

The parameter value

• Required: true
• Type: String
• Default: none

This tag is available for use inside the body of the following tags:

• <@td.assemblyEditorUrl>
• <@td.assemblyViewerUrl>
• <@td.pageUrl>
• <@td.portalUrl>
• <@td.searchResultUrl>
• <@td.themeFileUrl>
• <@td.viewerUrl>

This tag contains the following attributes:

contextualizedChild

A Contextualization object. If specified, the preview rendition of this contextualized child will be used.

• Required: false
• Type: Contextualization
• Default: none

portal

The PortalIdentity object. If not specified, there must be a ${portal} attribute in scope.

• Required: false
• Type: PortalIdentity
• Default: The PortalIdentity object on the current page

scope

The scope of the @var attribute. Valid values are "page" and "request".

• Required: false
• Type: String
• Default: "request"

searchResult

The SearchResultDocument object. This data is placed into the model of the searchResults.ftl page and returned by <@td.Search> and <@td.groupSearch> tags. If not specified, there must be a ${doc} variable storing a SearchResultDocument object in scope.

• Required: false
• Type: SearchResultDocument
• Default: SearchResultDocument object stored in a variable called ${doc}

url

The ContentLocator of the item. If context information is provided via other attributes, it will override any context information in this object.

• Required: false
• Type: ContentLocator
• Default: none

urlQuery

The query string. This value will NOT be URL-encoded, so it should be encoded already. You can also use nested <@td.urlParam> tags to specify individual URL parameters in a URL-escaped way.

• Required: false
• Type: String
• Default: none

urlString

The ContentLocator of the item. If context information is provided via other attributes, it will override any context information in this object.

• Required: false
• Type: String
• Default: none

var

The name of the variable used to access the result.

• Required: false
• Type: String
• Default: none

Titania Delivery determines whether mapViewer.ftl or viewer.ftl will be rendered depending on the content.

This tag contains the following attributes:

name

The parameter name.

• Required: true
• Type: String
• Default: none

value

The parameter value.

• Required: true
• Type: Object
• Default: none

<image>

<xref>

Converted into <a> tags. The <desc> element, if present, is converted into @title attribute. The @href attribute is untouched; link and graphic references are updated to web URLs automatically after the XSLT runs. However, you can customize this behavior by overriding the named get-xref-href template.

Processing of <xref> also calls the named extra-xref-attrs template. By default, this sets target="_blank" on links whose @scope is not "local".

<note>

• The @type attribute value is included in the output @class attribute.
• A <h4 class="noteHeader"> element containing the @type value is prepended to the note contents.

<table> and <simpletable>

<title>

• Top-level map and topic titles become <h1>.
• Second-level topic titles become <h2>.
• All other topic titles become <h3>.
• Section and example titles also become <h3>.
• All other titles become <h4>.

<dl>

<dlentry>

<xmlelement>

<xmlatt>

<tm>

<menucascade>

The children of this element are joined together using a joining character that can be controlled using the $menucascade-separator parameter ( ⇒ by default).

<object data="*.mp4">

<lines>

<sl> and <sli>

Link Groupings

The default template for <related-links> looks like this:

<xsl:template match="&related-links;[.//&link;]"
  priority="-20" mode="#default html">
  <div>
    <xsl:call-template name="generate-common-attrs" />
    <xsl:call-template name="do-child-links" />
    <xsl:call-template name="do-sequence-links" />
    <xsl:call-template name="do-sibling-links" />
    <xsl:call-template name="do-link-groups" />
    <xsl:call-template name="do-other-links" />
    <xsl:call-template name="do-parent-links" />
  </div>
</xsl:template>

It calls the following named templates, in this order.

1. do-child-links (role="child")
2. do-sequence-links (role="previous" and role="next")
3. do-sibling-links (role="sibling")
4. do-link-groups (links wrapped in <linklist>)
5. do-other-links (all other links except @role="parent")
6. do-parent-links (role="parent")

You can override this template to change the order of links in HTML output, or to eliminate various groups of links.

Default Link Structures

The <linklist> element is converted into an <ol>, and each link it contains is wrapped in <li>. Other links are simply placed within <div> elements. Within its container, each link consists of

1. An <a> tag, with the link itself.
2. For child links, a <div> containing the short description of the topic, if present. (The DITA engine also generates or populates <desc> tags for related links when possible in the XML presented to the stylesheet.)

Customizing Link Presentation

The built-in related links module includes two special modes for customizing link presentation.

get-link-label

Used to get a label for the link. This is separate from the link text. By default, the module provides "Previous Topic," "Next Topic," and "Parent topic" for @role='previous', @role='next', and @role='parent' links, respectively.

get-link-class-tokens

This mode is used to retrieve any additional HTML @class attribute tokens to include on the generated wrapper element for the link. By default, the @class attribute will include the link tag's specialization hierarchy as well as the value of the @role attribute.

For example, to provide custom @class and label for links whose @role is "sibling", you could add code like the following.

<xsl:template match="&link;[@role='sibling']" mode="get-link-label">
  <xsl:text>Sibling Topic:</xsl:text>
</xsl:template>

<xsl:template match="&link;[@role='sibling']" mode="get-link-class-tokens">
  <xsl:text>sibling-link my-special-class</xsl:text>
</xsl:template>