The package API

<@package.add>

Adds a document to the archive. The document is not modified in any way, and is simply placed as-is. This is primarily for non-textual document formats, like PDF, Microsoft Office, images, video, and audio files.

@document

Required. The PackageDocument instance to insert.

@dest

Optional. The location in the archive to place the document. If not specified, the location in the archive will be determined by the docLocator or contextualizedDocLocator patterns from the config.json file.

@failOnDuplicate

Whether to fail the packager if an attempt is made to add a duplicate entry to the archive. If false (the default), subsequent adds to the same package entry will fail silently. Otherwise the packager will fail with an exception.

@representation

Optional. An array of ItemRepresentationTypes, in priority order. The first type for which there is database content for the specified document will be placed in the package. This attribute supports conversion of non-web-friendly graphics to web-friendly renditions for display inline in an HTML page. For example, if the current pkgDoc is an EPS file referenced from a web page, the following directive would place the PNG rendition in the package (if available), or fall back to the original file type.

<@package.add document=pkgDoc representation=["PREVIEW","ORIGINAL"]/>

For example:

<@package.add document=curDocument/>

<@package.put>

Puts files and directories from the portal theme to the archive.

@src

The portal theme file or directory to add, as a path-like string. If the value begins with a forward slash (/), the location is found from the root of the portal theme. Otherwise, the path from the portal theme root is calculated from the current lexical template location. Relative src paths may include "../" components to refer to the parent directory.

If the source is a folder, its contents will be recursively copied. If the path ends with "/*", only the contents of the named folder will be copied. Otherwise, the final folder in the src path (and its contents) will be copied.

@dest

Optional. The path in the archive where to put the copied source files or folder. If not specified, files and folders are added at the root of the archive. The @dest attribute value is implicitly an absolute directory path, so leading and trailing slashes are assumed, whether or not the template author writes them.

@failOnDuplicate

Whether to fail the packager if an attempt is made to add a duplicate entry to the archive. If false (the default), subsequent adds to the same package entry will fail silently. Otherwise the packager will fail with an exception.

For example:

<#--
Copy the theme's /static directory and its contents to /stuff/static in the archive.
-->
<@package.put src="/static" dest="/stuff/"/>

<#--
Copy the contents of the theme's /static directory into the /stuff directory in the archive.
-->
<@package.put src="/static/*" dest="/stuff"/>

<#--
Copy favicon.ico from the theme's /static directory to the root of
the archive.
-->
<@package.put src="/static/favicon.ico"/>

<#--
Copy all files from the template's parent directory's "images" sibling directory 
into the archive root "images" entry.
-->
<@package.put src="../images/*" dest="images"/>

<#-- 
Same as preceding example.
-->
<@package.put src="../images"/>

<@package.preprocessCSS>

TD online portals support LESS or SASS stylesheets, which must be compiled into CSS before being used by browsers. This directive is similar to <@package.put>, except that it compiles the LESS or SASS file, as determined by file extension, to CSS before placement in the archive.

@src

Path to a LESS or SASS file in the portal theme. Relative paths will be resolved from the current lexical template location, and may include "../" components to refer to the parent directory.

@dest

The path in the archive where to put the compiled CSS file. This is implicitly an absolute path from the archive root. A value must be supplied; there is no default destination.

@encoding

The character encoding to use for the contents of the generated CSS file. Optional. If not specified, the configuration's defaultContentEncoding property is used.

<@package.preprocessCSS src="/static/style/main/default.scss" dest="/static/default.css"/>

<@package.generate>

Executes the nested Freemarker code to generate a file, placing it in the archive at the specified location.

@dest

The location in the archive for the generated file.

@encoding

The character encoding to use for the contents of the generated file. Optional. If not specified, the configuration's defaultContentEncoding property is used.

For example, the following code will generate a /COPYRIGHT.txt file in the bundle using the current year:

<@package.generate dest="/COPYRIGHT.txt">
Copyright (c) ${.now?string.yyyy} Titania Software. All rights reserved.
</@package.generate>

<@package.generateDoc>

Similar to <@package.generate> but instead generates a file using Freemarker that will contain/represent the content of the document. Many document types, like XML documents, should not be included in a package as-is. Instead, it should be wrapped in a page containing branding and navigation.

@document

The PackageDocument instance whose page to generate. The location in the archive will be determined by the config.json file's docLocator or contextualizedDocLocator patterns.

@encoding

Optional. The character encoding to use for the content of the file. If not specified, the configuration's defaultContentEncoding property is used.

<@package.docContents>

Used for inserting a textual, XML, or HTML document within the context of a <@package.generateDoc> or <@package.generate> directive. This is similar to the <@td.content> directive for online templates, adapted for package use.

@document

Required. The document instance to insert.

@expandReferences

A boolean indicating whether references to other documents should be rendered inline; primarily for use with DITA maps. The default is false.

@installMedia

A boolean indicating whether referenced media should be installed in the archive. The default is true. Specifically, the HTML will be scanned for the following elements and attributes:

• img/@src (images)
• video/@src
• audio/@src
• source/@src
• object/@data

When generating the HTML representation of content, any references in the source should be left unchanged. The packager will automatically rewrite these HTML references to use the appropriate relative URI in the package.

This works in addition to the packager XSLT function package:mediaReference() function described below.

@storeResult

If set to false, the rendered output will not be stored in the system cache. The default is true.

@timeout

Optional. Set the XSLT transformation timeout in milliseconds.

@xsl

If the content is XML, this directive will specify the XSL transformation in which to pass the content through. If omitted, the XML will be inserted as-is. If the value begins with a slash (/), it will be considered relative to the /xsl directory in the portal theme. Otherwise, it will be considered relative to the packager root directory.

Nested <@package.xslParam> directives may be used to pass parameters to the XSL transformation.

<@package.xslParam>

Used to specify xsl parameters inside a <@package.docContents> directive. This is similar to the <@td.xslParam> directive for online templates.

@name

Required. The name of the XSL parameter.

@value

The value of the parameter. This can be a string, numeric, boolean, sequence, or hash freemarker value.

<@package.statusMessage>

Updates the status message of the offline package request with the rendered directive contents. The status message may be displayed in the status window as the package is being prepared.

<@package.log>

Writes a log message to the freemarker template output. Log messages will only be written if the level specified in the directive attribute is at or above the log level configured in the packager.

level

The log level at which to write the message. The allowed values are, "DEBUG", "INFO", "WARNING", or "ERROR". If not specified, defaults to "INFO".

package.relativeUri(to[, from])

Used within <@package.generate> or <@package.generateDoc>, this function determines the relative URI to the given package location from the given source location.

to

Required. The object being referred to. This can either be a string containing the target path within the package, or a PackageDocument object, in which case the configuration's @docLocator will be used to determine the target location.

from

Optional. The package location to use as the base when generating the relative URI.

If from is omitted, the current location (as specified by the parent <@package.generate> or <@package.generateDoc> directive) is used.

<a href="${package.relativeUri('/index.html')?html}">Link</a>
<a href="${package.relativeUri(doc)?html}">${doc.metadata['title'][0]?html}</a>
<img src="${package.relativeUri('/static/images/logo.png')?html}">

package.getDocLocation(doc)

This function returns the default location in the archive for the output artifact corresponding to the given input document, as calculated using the rules in config.json.

doc

The PackageDocument instance whose output location to retrieve.

package.setStatusMessage(message)

This is a functional version of the <@package.statusMessage> tag; updates the current status message for the package as it executes.

package.currentPackageLocation

When inside a directive that is writing to a location in the package, like <@package.generate> or <@package.generateDoc>, this variable contains the location of the entry in the output archive.

package.hexSignatures

When digital signing is enabled, this variable will contain a map of digital signatures generated for files placed into the package. The key in the map is the location in the package of the files that have been generated so far; the values are the digital signatures for those files, as hex-binary strings.

package.base64Signatures

When digital signing is enabled, this variable will contain a map of digital signatures generated for files placed into the package. The key in the map is the location in the package of the files that have been generated so far; the values are the digital signatures for those files, as Base64-encoded binary strings.

package.signaturesXmlDoc

When digital signing is enabled, this variable will hold a DOM Document representing an XML Signatures file in the EPUB signature format for all files in the package (so far). This document can be manipulated using Freemarker's XML processing APIs. For example, the XML could be serialized to the package using instructions like the following:

<@package.generate dest="META-INF/signatures.xml">
  ${package.signaturesXmlDoc.@@markup}
</@package.generate>