Parameter Files — XML
We will be using the sample parameter file paramsletter.xml in the samples directory as an example throughout this chapter. The default location for AppendPDF Pro on Windows is C:\Appligent\AppendPro\ and AppendPDF is located in C:\Appligent\AppendPDF. On other platforms, it will be wherever you installed it. The paramsletter.xml AppendPDF Pro example contains most of the features described in this chapter for the purpose of explanation and examples.
Note: AppendPDF does not have all the capabilities that are shown in the examples (Comparing AppendPDF Products provides an overview of the differences). Information that is specific to AppendPDF Pro will be followed by the notation: (AppendPDF Pro only).
AppendPDF and AppendPDF Pro require a parameter file to specify how you want to build a new document. This chapter explains XML parameter files, while Parameter Files — Text (AppendPDF Pro) and Parameter Files — Text (AppendPDF) describe text parameter files:
- XML — the parameter files using XML to code parameter specifications.
- Plain text — the text parameter files used by earlier releases of AppendPDF Pro and AppendPDF. These are supported to maintain backward compatibility with existing workflows. New features will only be available using XML files.
An XML parameter file is a text file containing the XML markup that specifies how AppendPDF Pro or AppendPDF will build your new document. You can specify the name of the output file, list the files to be included in the appended document and set many other options to establish how you want the final document to look when it is opened by the end user.
The parameter file includes:
- <outputpdf> — Output File is the name (including directory path) of the new, appended file.
- <sourcepdfs> — Source Files are the documents to be used for appending, including page ranges and Table of Contents entries.
- <TOC> — Table of Contents information includes the table of contents file, alternate bookmark text, and the stamp file for the table of contents (AppendPDF Pro only).
- <coverpage> — Cover page information includes the cover page file to be used and the stamp file for the cover page (AppendPDF Pro only).
- <docinfo> — Document information is Title, Author, Subject, Keywords, and custom fields. These are viewable within Adobe Acrobat and Acrobat Reader.
- <extras> — Extras specify additional information such as how the document should open or a stamp file for the body of the document.
Elements and structure
We use XML to describe the parameters that AppendPDF Pro and AppendPDF uses to append documents together. As we describe XML elements, there are two sections:
- A tree view of the elements, which describes the elements and shows how they are related.
- Examples of XML code for each element.
An element table contains the following information:
- Element — The element tag.
- Required — Whether the element is required (✔) or optional (blank). If the child of an optional element is marked required, it is only required if the parent is used.
- Content — what information the element contains, i.e., what it specifies. Note that an element can either contain data, or be empty. If it is empty, nothing else is needed.
Note: Empty element tags can be entered using the beginning and end tags together or by using a simpler tag placing the slash “/” after the tag name as shown below:
All of the tables in the XML Parameter chapter that describe the structure of elements use notations and indents to indicate specific things about individual elements:
- The element tree structure shows the topmost element as being expanded with child elements below.
- The Level column indicates what level from the top parent element described in the table, the current child element resides.
- The notation “+” indicates the element is collapsed and is a parent which contains child elements within its structure.
- Indents are used to assist in understanding the structure levels of the elements in the table.
- When there are elements that come before the current element in the <appendparam> structure, and they are not being shown, there will be a ⇔ symbol before the element tag name in the table.
- Some parent elements contain several options. When only one of the options can be used at a time the word “OR” will appear before the element tag name in the table.
The XML parameter file contains content and design information for the document that will be built by AppendPDF Pro or AppendPDF. The following sub-chapters describe in detail how to build parameter files in XML format.