Introduction to Spruce

This topic explains the Spruce Executable process and introduces the Spruce User Interface (UI), which is also referenced as the Template Designer in this document. These are the major components of Spruce.

Overview

Spruce, a Cypress module, enables you to produce complex, dynamic documents that require letter quality composition and layout control (e.g., statements, invoices, policies, and other document types built from varying amounts of input data). The documents are created by merging raw XML data into an XML template and applying user-defined and customized styles referenced by the template. Output documents are sent to the DocuVault in their formatted state.

Spruce performs automatic page overflow and invokes dynamic headers and trailers, depending on the amount of data you provide. You can build paragraphs with automatic word-wrap and justification when placing text, bar codes, or images onto the page and invoke boxes and shading, their size and positioning dependent on the input data. Spruce gives you complete control over form overlays, paper stock, page orientation, and duplex printing.

You can create customized templates containing a variety of user-defined formatting features that can be applied to your raw XML data. Spruce’s formatting features include font, font size, color, paragraph justification and layout, and insertion of graphics. For more information on using these features, see Working with Templates . Spruce merges the XML data into your predefined template and yields output documents in the DocuVault in the internal Cypress format. You also can specify how and where to send your documents (e.g., by e-mail or to a printer).

Creating a Document with Spruce

You can run Spruce as a stand-alone module that creates documents and queues them to a specified device. You can also invoke it through the Content Processing Facility (CPF), which returns the created document in a doc_list for further processing.

Spruce requires three files to run:

•

The template that describes the document layout.

•

A data file of raw input data to be merged into the template.

•

A schema that describes the layout of the data.

The template and schema are loaded from the DocuVault. The data file is specified at run time.

Document Creation Process

There are four phases in the Spruce document creation process that take place before the final document output:

1.

Spruce reads the template and constructs the internal structures based on what is contained in the template. If the template references Include files, they are merged into the template. See Using INCLUDE Templates

2.

Spruce merges the variable data from the input XML file in specified locations within the document. Any conditional or looping logic present in the template is executed. All content for the final output of the document is constructed.

3.

Spruce constructs the formatting details. Each word within a Line, each Line within a Paragraph, and each Paragraph within a Block are positioned according to the specified justification values in the template. As paragraphs are built, page overflow is detected and handled as specified. Font and color switching are also executed in this phase. See Working with Templates

4.

In the final phase, the documents are produced in Cypress internal format. If Spruce is being run as the stand-alone executable, the document(s) are stored into the DocuVault. If Spruce is invoked from CPF, then the output documents are built into the document list that is returned to CPF.

Phases 2 through 4 are repeated to produce each individual output document. For final documents produced, by Spruce running as a stand-alone executable, a job ticket is built, if requested.

Spruce enables you to perform these tasks:

•

Execute control statements (e.g., If, Switch, While, and For objects) that provide complete control over document content.

•

Maintain pagination with the appropriate headers and trailers. Orphan and Widow line settings are invoked.

•

Use global variables to accommodate items such as page numbers.

•

Control fonts, font size, color, paragraph type, paragraph justification, underlining, and tabs.

•

Insert graphics.

•

Use line drawings and shading.

•

Maintain control over page elements (e.g., stock, orientation, simplex/duplex, front/back side, and form overlays).

•

Control document security, destination devices and recipients, and document retention times.

Template Designer Features

Using Spruce, you can design custom templates to use to create documents containing information and formatting specific to your company’s requirements. Additionally, you can modify existing templates and include sections in your documents of other templates that contain commonly used information.

Each template consists of XML data that describes the layout of the document. You can use these features to design a custom template:

Format Section

The Format section contains Style, Color, and Tab objects.

•

Style objects are used in the Document section to control the document’s format provide various attributes for text and drawing. You can specify font name, size, color, justification type, etc.

•

Color objects describe predefined or custom colors that can be used elsewhere in Spruce to apply to text or graphics.

•

Tab objects describe a horizontal location and justification value for positioning text into columns. for more information.

Document Section

The Document section describes the format and layout of the document’s pages. It controls looping through the input data and contains various objects nested within each other, in a tree structure. You also can use it to specify attributes of the document, including the title, retention time, destination device, and so on. See Creating a Template for more information.

Pages Objects

Spruce uses Pages objects for text that may overflow the physical page. A Pages object contains three sub-objects: headers, a body, and trailers. These sub-objects are executed in this order:

•

Header

•

Body

•

Trailer

If the body exceeds the page size, it is interrupted and the trailer is executed, a new page is started, the header is executed, and the body continues where it left off. Each of the headers, body, and trailers can contain one or more blocks. See Pages Properties.

Block Objects

Blocks are one of the basic objects within a template. A block describes an area on a page where text or graphics are placed. The physical dimensions of a block are specified in terms of height, width, and vertical and horizontal positions. See Block Properties.

Paragraph Objects

Paragraphs describe multiple lines of text with various attributes. Blocks can contain zero or more paragraphs. There are several paragraph types. A normal paragraph describes the typical single-column paragraph. The labeled paragraph precedes the paragraph with a label, such as a bullet or paragraph number. Paragraphs can have one of the following justification types: left, right, center, and full. You also can specify attributes with the paragraph, including font name, font size, color, and underlining. See Paragraph Properties.

Control Statements

Control statements in the template allow for decisions and looping.

•

An If statement can be used to make a decision on whether to include certain items.

•

While statements can be used to loop until a certain condition is met.

•

Switch statements will choose one of a number of cases.

All of these statements contain an expression that will be processed in the same manner as expressions in Report Distribution Manager (RDM) or CPF, which will allow processing of strings and numbers that already exist in Cypress.

Variables

Variables can be read from the input file and included in the template to hold immediate results.

•

Normal variables are cleared after each pass-through.

•

Global variables retain their values across passes.

Several predefined variables are available to set Cypress-specific items, including document title, retention times, and job ticket descriptions. See Variables.