Packager Variables

The PackageDocument Data Structure

The documents array contains a list of objects describing the properties and metadata of each document to be included in the package. The packager script iterates over these documents, placing each into the appropriate location in the bundle, possibly after transformation (e.g. XML to HTML5).

In addition, each document contains an array referring to the other files, like graphics or, for DITA Maps, contextualized topics. The packager infrastructure provides various utility mechanisms for automatically including graphics and contextualized DITA topics into generated packages, but you can use the relationships to perform custom, manual processing of such files.

The formal definition of the PackageDocument structure follows (TypeScript syntax).

class PackageDocument {
  // Properties of the file itself.
  key: string;
  project: ProjectInfo;
  label: string; // file name, e.g. foo.xml
  projectPath: string; // path within the project, e.g. /path/to/foo.xml
  folderPath: string; // The path of the folder containing the file, including leading /
  basename: string; // The base name of the file
  extension: string; // The file extension
  contentType: string;
  size: number;
  lastModified: Date;
  createDate: Date;
  packageRoot: boolean; // Whether this document is a package entry-point, that is,
  // included explicitly in the package request.
  isVirtual: boolean; // Typically for topichead virtual documents.
  // Indicates if there is a search record for this document.
  
  // A map of strings to arrays of strings
  metadata: {[name: string]: string[]}
  
  // The properties of the document, analogous to the 'properties' variable in online
  // viewer page templates.
  properties: {[name: string]: any}
  
  // For documents referenced by other documents
  // (map-to-topic references, images, etc.), the
  // referencing document.
  context: PackageDocument;
  hasContext: boolean;
  
  // For topics referenced by maps, the topicref ID.
  refId: string;
  
  // 'Child' references, e.g. topicrefs, graphics.
  outgoingReferences: Reference[];
  
  // Helpful for building search indices.
  keywords: string[];
  textContents: string;
}

enum ReferenceType {
  // Inclusions, like DITA topicrefs or xincludes
  PARENT_CHILD,
  // Non-contextualizing references, like hyperlinks
  LINK,
  // Graphic references
  GRAPHIC,
  // XML doctype references
  DOCTYPE,
  // Generic, non-DITA links
  FILEREF
}

class Reference {
  parent: PackageDocument;
  child: PackageDocument;
  type: ReferenceType;
}

class ProjectInfo {
  key: string;
  name: string;
}

Freemarker package directive template output

A packager freemarker template's primary purpose is to create a zip archive as specified by the @package.* directives. It will also produce text output as a result of normal freemarker template processing. The output generated by the @package.* directives will be an informational transcript of the actions taken, including warnings about any requested actions that may not have been completed as expected. If the configuration buildLogEntry is not null, the output will be written to the designated package entry.