Working with Templates

This topic provides information about creating, modifying, and deleting templates.

Introduction

Spruce enables you to create customized templates for your unique business needs. In general, a template contains a document with various objects, including Pages, Body, Blocks, Paragraphs and Lines. You can insert Boxes and conditional statements around many of these objects.

This topic takes you through steps for creating many of the elements that comprise a template. To view an example of how these elements display in Spruce, see Template Tree View It also provides instructions for modifying, deleting, exporting, and importing your templates.

Selecting Template Viewing Options

Before you create a template, select the options to apply to your screen displays from the View menu. The options you choose determine how your data displays.

To choose your options

Select the View menu on the Spruce UI main window, and click Options.

The Options dialog displays.

Click one of these option buttons in the Unit of Measure area:

•

Inches

•

Centimeters

•

Points

For example, if you choose Inches, Spruce screens will display with inches as units of measure, as appropriate.

This option controls only how values are displayed in the Spruce UI and does not affect how they are stored in the template XML.

Enter the appropriate numerical values in the Template Page field and the Data Page field in the Real Precision area.

This option specifies the number of decimal digits that will display when you print a real number. Valid values range from 0 through 7. The settings control only how real values are displayed in the Spruce UI and do not affect how they are stored or emitted onto the document pages.

Creating a Template

To create a template

From the Template menu, click New.

From the Template Toolbar, click the New icon.

The New Template dialog displays.

Enter the name of the template in the Template Name input field, and click OK.

The template will not be saved to the DocuVault until you click the Save button.

In this example, the Sample Statement template name is used. The name of the template you are creating displays in the tree on the left side of the screen with the Template icon next to it. The default format and document properties display to the right of the screen, and the name of the template displays at the top of the screen.

Create a Color to be used with your template.

From the Template Tree view, select and right-click Format } Append } Color.

From the Template Tree view, expand Format to display Style Default. Right-click Style Default and select } Insert } Color.

The “Color” Properties dialog displays.

Enter the name of the color in the Color Name input field.

Select a standard color from the list below the input field drop-down. You also can create a custom color.

Click OK.

Your Color object displays under the document section of the Template Tree view.

Create a Style for your template.

As you create styles for your template, they are stored in Spruce and will display in the style drop-down menu along with the default style.

From the Template Tree view, select and right-click Format } Append } Style.

From the Template Tree view, select and right-click Style:Default } Insert } Style.

The “Style” Properties dialog displays.

Enter a name for the style and complete any other appropriate fields to specify the desired style properties (e.g., font, font height, font width, and font color).

The font, fontcolor, overline, underline, just (justification), linecolor, and fillcolor have drop-down lists of available values.

Click OK.

Create a Tab for your template.

From the Template Tree view, select and right-click Format } Append } Tab.

From the Template Tree view, select and right-click Style:Default } Insert } Tab.

The “Tab” Properties dialog displays.

Enter a name for the tab, and complete the fields with the appropriate information.

Click OK.

Create a Page or Pages for your template.

From the Template Tree view, select and right-click Document } Append } Pages.

The “Pages” Properties dialog displays.

Enter the appropriate information in the fields in the right column (e.g., the type of paper stock, page orientation, etc.).

Click OK.

After you create pages, each page and its associated Pages icon display in the Template Tree view. If you expand the icon, Spruce automatically generates a Body icon since a Pages object can contain only one Body. You can add Headers and Trailers as needed.

Create a Block for your template.

From the Template Tree view, select and right-click Document } Append } Block.

From the Template Tree view, select and right-click the Pages object you just created } Insert } Block.

The “Block” Properties dialog displays.

Enter the appropriate information in the fields in the right column.

The block represents the area within the document in which you will place text and/or graphics. Enter the location and dimensions. The Positioning and Page Attributes sections of the “Block” Properties dialog have lists of drop-down lists of available values. See Block Properties for detailed field descriptions.

To help you position blocks where you want them, Spruce enables you to draw a rectangle directly on the Document view. The location with corresponding dimensions is stored and automatically inserted into the next block you create within the Template Tree view.

Click OK.

Create a Box for your template.

From the Template Tree view, select and right-click Document } Append } Box.

From the Template Tree view, select and right-click the block you just created } Insert or Append } Box.

The “Box” Properties dialog displays.

Enter the appropriate information in the fields in the right column.

The linetype, filltype, and style fields all have drop-down lists of available values. Enter the appropriate numerical values in the extend up, extend down, extend left, and extend right fields. See Box Properties for detailed field descriptions.

Click OK.

You can also create Box by surrounding an existing object. (See Surrounding an Object for more information.)

Create a Paragraph for your template.

From the Template Tree view, select and right-click the box you just created } Append } Paragraph.

From the Template Tree view, select and right-click the box you just created } Insert } Paragraph.

The “Paragraph” Properties dialog displays.

Enter the appropriate information in the fields in the right column.

The style and just (justification) fields have drop-down lists of available values.

Select one of these justification types: center, full left, and right.

Click OK.

10.

Create a Line for your template.

From the Template Tree view, select and right-click the paragraph you just created } Append } Line.

The Line Editor dialog displays.

The Line Editor is where you enter the data in XML format. This data displays in your output documents. Documents are stored in the DocuVault in internal Cypress format.

Type the desired text in the Line Editor dialog. This text displays on the page in the location of the Block that contains this Line.

Click Validate to ensure that the XML text is correct.

•

If the text is correct if this message box displays:

•

If the text is incorrect, an error message displays.

Right-click in the Line Editor dialog to display this context-sensitive menu:

The Line Editor enables you to Insert all of the items listed on the menu when you are creating a line. It also enables you to use the Surround, Copy, Cut, Delete, Paste, and Select All options. For more information, see Line Editor Properties

11.

Create a Header for your template.

From the Template Tree view, select and right-click the Pages object you created earlier } Append } Header.

From the Template Tree view, select and right-click the Body that was automatically created } Insert } Header.

The “Header” Properties dialog displays.

Enter the appropriate information in the fields in the right column. Select from the available values on the drop-down lists. See Header Properties for detailed field descriptions.

Click OK.

12.

Create a Trailer for your template.

From the Template Tree view, select and right-click the Pages object you created earlier } Append } Trailer.

The “Trailer” Properties dialog displays.

Enter the appropriate information in the fields in the right column. Select from the available values on the drop-down lists. See Trailer Properties for detailed field descriptions.

The “Trailer” Properties dialog has the same fields as the “Header” Properties dialog.

Click OK.

While creating a template, you can click the Document tab or the Document button to view how your output document will look. See Document Tab

Using INCLUDE Templates

Include templates are especially helpful for adding common objects to larger templates without having to re-create them, thus saving time and duplication.

To create an include template

From the Template menu, click New.

Click the New button.

The New Template dialog displays.

Type the name of the include template in the Template Name input field (e.g., Example Include Template).

Select the Is an INCLUDE template check box so the check mark displays.

Click one of the option buttons that display in the Include Type area.

•

Format contains Colors, Styles, and Tabs.

•

Document contains objects such as Blocks or Boxes with the document level.

•

Block contains objects such as Paragraphs with the block level.

Click OK.

Several changes occur in the Spruce UI main window:

•

The Include template displays in the tree view on the far left side of the screen and the new name of the Include template displays below the main Include with their respective icons

•

The Tree view and Text view are available.

•

The Schema, Sample Data, and Document tabs are deactivated or grayed out.

An Include template has no schema or sample data and cannot display a document view.

Add the desired colors, styles, and tabs to the Format Include template the same way you created and added them when you created the template. SeeCreating a Template.

Click Save when you are finished specifying properties for your INCLUDE template.

To incorporate an include template into an existing template

Using the previous examples, select the “Sample Statement” template and click the Tree tab to display the tree view.

Expand the Format section of the template and right-click on a color, style, or tab of your choice } Insert } Format Include.

The “Format Include” Properties dialog displays.

Type the name of the include template in the Format Include Name input field.

Select a name from the drop-down list of existing include templates.

For this example, select the Example Include Template you just created.

Click OK.

The original Sample Statement template now contains the new Example Include Template you just created. The Include template displays in the Template Tree view and its associated icon is highlighted in yellow.

Refresh the dialog by clicking one of the tabs at the bottom of the right pane of the Spruce UI main window (e.g., Document). Then click the Template tab to return to the Tree view.

You can see the changes in the Template Tree view. The elements that comprise the Include template are highlighted in yellow.

When an Include template is first inserted or appended, it displays as a single generic icon. After the template has been reloaded (e.g., by clicking the Document tab), the Include template is expanded to show its actual contents. The icons are highlighted in yellow and the contents cannot be modified.

Be careful not to delete an Include template that is in use by another template or Include template. If you do, those templates will no longer load or run. To resolve this issue, create a temporary dummy Include template with the same name as the one you deleted, then open each template/Include template that uses this Include template and remove the reference. After all of your Include templates/templates are cleaned up, you can safely remove the dummy Include template.

Cloning Templates

Cloning is a convenient feature that allows you to copy an existing template with all of its attributes. You can then give the template a new name and modify only those items you wish to change, without having to create a brand new template from scratch.

To clone a template

On the left side of the Spruce UI main window, under DocuVault, click the name of the template you want to copy.

From the Template menu, click Clone.

Click the Clone icon on the Shortcut toolbar.

The New Template dialog displays.

Enter a name for the new template in the Template Name input field.

Click OK.

The new template name displays under the DocuVault tree structure.

Resetting Templates

If you modify your template then decide to discard the changes without deleting the entire template, you can use the Reset feature in Spruce.

To reset a template

If you make modifications to your template, then decide not to keep them, click the Reset icon.

From the Template menu, click Reset.

This message box displays:

Click Yes to disregard your changes and reload the last saved version of the template.

Click No to continue.

If you decide to keep the changes you made, you still need to click the Save icon to save the new information.

Working with Schemas

A schema describes the layout of incoming XML data. You can add, delete, and define variables and arrays within a schema.

Schema consists of the global and document sections. The global section describes data items that appear only once in the data and apply to the entire Spruce execution. You can add or delete variables in the global section. The document section describes data items that are repeated in the data file for each individual document created by Spruce. You can add or delete variables or arrays in the document section.

An array is a list of variables that can be repeated as many times as necessary in the data file. Nested arrays are supported (up to 10 levels deep) with these requirements:

•

All array names must be unique. For example, if array A contains arrays B and C, array D cannot also contain arrays with the names of A, B, or C.

•

Variable names can be reused in different arrays. For example, arrays A and B can both contain a variable X.

•

An array must contain at least one child (either an array or a variable). A completely empty array will generate a schema error.

The Tree view displays the data type (i.e., string, integer, real, or boolean) for each object in the schema. See Schema Tree View

The step-by-step process in this section details how a variable for customer country is added to the schema, using the Sample Statement template.

To add a variable to the schema

From the Schema Tree view, expand the document section and right-click cust_zip[integer] } Insert } variable to display the Schema “variable” Properties dialog.

Type the name of the variable in the name input field.

When adding variables:

•

The first character in the name of the variable must be a letter or underscore, followed by any combination of letters, numbers, and underscores.

•

You can use uppercase and lowercase letters.

•

Do not use spaces or special characters in the variable name.

•

Ensure that the name you choose for the variable is not a duplicate.

Select string from the drop-down list to display in the type field.

Click OK. The new variable now displays in the Schema Tree view.

Ensure that the variables you add to the schema are also coded in the template so they will function correctly.

Working with Sample Data

Sample data is generated as you create your schema. It is test data that will be displayed only, not the real data in your output documents. It is used, however, to create sample documents to show you what your output documents will look like. You can test to see if your variable data will display properly by clicking the Document tab at the bottom of the main panel. The Tree and Text views display the data type (i.e., string, integer, real, or boolean) for each object in the sample data.

•

The global section contains the global variables or variables that will be present in all of your documents (for example,company name). You can view variable properties and change values in the respective properties dialogs here.

•

The document section contains the variables that will change for each customer (e.g., customer name) and the item details for each customer (e.g., the check amount, date, and description). You can view the properties in this section and change the values in the respective properties dialogs here. You also can add or delete item details before or after another item detail.

The step-by-step processes detailed in this section illustrate how you can change Sample Data to verify that your template is working correctly. The Sample Statement template and associated Sample Data are used in this section.

To review sample data

Select the Sample Statement template in the navigation panel on the Spruce UI main window.

Click the Sample Data tab at the bottom of the main panel, then click the Tree tab to display the sample data for the Sample Statement in the Tree view.

Click the plus sign next to global, document, and the first few occurrences of checks to display the associated detail. Note the items highlighted in yellow. These items display where changes occur as you change data to test your template.

Click the Text tab to display the related XML.

Click the Document tab to display the test output document. The highlighted data that will be compared to the test data when you change object values in the next section.

To test data by changing object values

From the Sample Data Tree view for the Sample Statement template, right-click the “cust_addr2 [string]” object } Properties to display the cust_addr2 Properties dialog.

Enter Apt. 5496 in the value input field.

Click OK. In the Tree view, the value of the cust_addr2 [string] object changes to Apt. 5496.

Right-click the check_amount [real] object } Properties to display the chk_amount Properties dialog.

Type 920.73 over the existing value, 845.30 in the value input field.

Click OK. The value of the chk_amount [real]object changes to 920.73 in the Tree view.

Click the Document tab to display how the output document will look.

•

Compare the highlighted portion of the customer’s address in the output document to the original one at the beginning of this section. “Apt. 5496” was added to the original address.

•

Compare the highlighted portion of the check amount in the output document values above, to the check amount value in the original output document. The amount changed from $845.30 to $920.73.

The test Sample Data shows that the template is working properly and the address and cost values changed as expected. You can apply this method of testing on all of the objects within the Sample Data.

To add before, add after, or delete item detail objects

In the Tree view, right-click an existing detail item to display Add Before, Add After, and Delete.

Click Add Before to add the item detail object above the selected item.

Click Add After to add the item detail object below the selected item.

Click Delete to delete the item detail object.

This feature allows you to create additional data or delete existing data and to modify properties for testing varying amounts of data.

Modifying Templates

Once you have created a template, you always can modify it later. You can add new items, delete existing items, or modify the properties of existing items. The first step-by-step process in this section demonstrates adding a new Block to the existing Sample Statement template that was created at the beginning of this topic. See Creating a Template.

To add a new item to an existing template

From the Template Tree view, select and right-click an existing block in the template tree } Insert } Block.

The “Block” Properties dialog displays.

Enter the appropriate information in the fields in the right column. See Block Properties for detailed field descriptions.

To modify an item in an existing template

From the Template Tree view, select and right-click an existing block in the template tree } Properties.

The “Block” Properties dialog displays.

Change the values in the appropriate fields.

Click OK.

To delete an item in an existing template

Do not use the Delete button or the Template } Delete option to delete individual items from a template. Those options are used for deleting the entire template.

From the Template Tree view, select and right-click an existing block.

Click Delete } Save.

The item is removed from the template and from the Template Tree view.

Deleting Templates

To delete a template

Highlight by clicking the name of the template in the Template Tree view.

Click the Delete icon.

This message displays.

Click Yes.

The screen is cleared, the template deleted permanently, and the name of the template is removed from the list of template names under your DocuVault.

Click No.

The delete request is canceled and your template remains intact.

Exporting Templates

Spruce enables you to export templates and include templates from your DocuVault to disk files for backup or importing into other DocuVaults.

To export a template

From the Template Tree view in the Spruce DocuVault, highlight the name of the template you want to export. (In this example we are using the Sample Statement template.)

From the Template menu, click Export.

Click the Export icon on the shortcut toolbar.

The Export Template dialog displays.

The name of the template you are exporting displays at the top of the Export Template dialog.

Click the browser button on the right side of the dialog to locate the directory to which you want to export the template.

The Open dialog displays.

Enter in the File name field the name of the file to which you want the template written, and click Open.

The path and the template file name display in the Template File field.

Repeat step 4 for File, Schema File, and Data File.

When naming the files for the template you are exporting, a default name is constructed for the three files to be exported. These names are the names of the template, followed by _template, _schema, and _data, respectively, with the appropriate extension (e.g., .xml or .xsd).

Click OK.

The template is now exported to the directory or DocuVault of your choice.

Click Cancel, to cancel the your changes.

To export an include template

From the Template Tree view in the Spruce DocuVault, highlight the name of the include template you want to export.

From the Template menu, click Export.

Click the Export icon on the shortcut toolbar.

The Export Template dialog displays.

Click the browser button on the right side of the dialog to locate the directory to which you want to export the template.

The Open dialog displays.

Enter in the File name field the name of the file to which you want the include template to be written, and click Open.

The path and the include template file name display in the Template File field.

When naming the file for the Include template you are exporting, ASG recommends that you include include in the file name.

Click OK.

The include template is now exported to the directory or DocuVault of your choice.

Click Cancel, to cancel the your changes

Importing Templates

Spruce enables you to import templates and include templates into your DocuVault from disc files that have been exported from the same or another DocuVault.

To import a template

From the Template menu, click Import.

Click the Import icon on the shortcut toolbar.

The Import Template dialog displays.

Type the name of the template in the Template Name input field.

Click the browser button on the right side of the dialog to locate the directory from which you want to import.

The Open dialog displays.

Browse to the desired directory. Files with extensions of .xml and .xsd display.

Click the template file of your choice, and click Open.

The Open dialog displays.

The directory path and template name automatically display in the Import Template dialog.

Repeat steps 3 through 5 for the schema and data files, so that all three fields have the necessary entries.

You must complete all three file fields correctly for the import to work. Each field must have the correct file name entered (e.g., the Schema File field contain the schema file). If any of the three items are missing or placed in the incorrect fields, you will be unable to import the template.

Select the Remove DocuVault References check box if you are importing this template from a different DocuVault.

Template XML files that are exported from the Spruce UI contain specific DocuVault references to items such as fonts, forms, stocks, and images. If you are importing this template into a different DocuVault, the Remove DocuVault References check box can be selected so the specific references will be removed and the items will then match just by name. If the template being imported was created by this DocuVault, then the Remove DocuVault References check box should be cleared so that the specific DocuVault references will remain intact. This ensures that each specific item is selected.

Click OK.

The template is now imported and the name displays under your DocuVault in Spruce.

Click Cancel, to cancel the your changes

To import an include template

From the Template menu, click Import.

Click the Import icon on the shortcut toolbar.

The Import Template Dialog displays.

Click the Include tab.

The Import Template dialog displays with the information for importing include templates.

Type the name of the include template in the Include Name input field.

Click the browser button on the right side of the dialog to locate the directory from which you want to import.

The Open dialog displays.

Click the include template file of your choice, and click Open.

The path and the include template file name display in the Include file title field.

Select one of the three options in the Include Type area (e.g., select the Format option for an include template that has formatting objects).

The Include Type selected must match the type of file being imported.

Select the Remove DocuVault References check box if you are importing this Include template from a different DocuVault.

Template XML files exported from the Spruce UI contain specific DocuVault references to items such as fonts, forms, stocks, and images. If you are importing this template into a different DocuVault, the Remove DocuVault References check box can be selected so the specific references will be removed and the items will then match just by name. If the template being imported was created by this DocuVault, then the Remove DocuVault References check box should be cleared so that the specific DocuVault references will remain in tact. This ensures that each specific item is selected.

Click OK.

The include template is now imported and the name displays under your DocuVault in Spruce.

Click Cancel, to cancel the your changes.

Using an Alternate Input File or XSL Style Sheet with a Template

You can specify an input file to use with a template. Additionally, you can select an XSL style sheet to be used to transform the data into XML data.

To specify an alternate input file

Select a template in the tree view, and right-click. The context menu is displayed.

Select Alternate Input. The Alternate Input dialog is displayed.

Enter the path for the input file you want to use in the Input Data File field.

Click the Browse button to locate and select the file you want to use.

Click the Validate against Schema button to test the input file against the template’s schema.

The input file data is validated against the schema. An message displays to indicate whether the validation was successful or failed.

•

If the validation failed, details for the error display in the message area in the bottom pane. Click OK to close the message and return to the Alternate Input dialog.

•

If the validation is successful

Optional. Repeat steps step 3. - step 4. .

Click OK.

To specify an XSL style sheet

Select a template in the tree view, and right-click. The context menu is displayed.

Select Alternate Input. The Alternate Input dialog is displayed.

Enter the path for the style sheet file you want to use in the Use XSL StyleSheet field.

Click the Browse button to locate and select the file you want to use.

Click the Perform XSL data transformation to file button. The Open dialog is displayed.

Enter a name for the file in which you want to store the resulting XML data.

The XML data is validated against the schema. An error message displays if the transformation fails:

Details for the error display in the message area in the bottom pane.

If an error message displays, click OK to close the message and return to the Alternate Input dialog.

Optional. Repeat steps step 3. - step 5. .

Click OK.

Surrounding an Object

Spruce enables you to surround an object or group of objects in the template with other objects. For example, a Block, a Column, or a Line can be surrounded by a Box, which will draw an outlined or shaded box around this object.

This function is useful when you have designed a template and you decide later that some object needs a Box around it, but all that content is already built. To add the Box without using the Surround function, you would have to delete all this content that was already built, create the Box, and then recreate all the content inside. To avoid doing all this, Spruce allows you to surround any appropriate content with a surrounding object without having to do anything to the original content.

For example, suppose a Block has been built that contains several Paragraphs and Lines, each with some rather complex content, along with some If and For objects, and you then decide that you want the Block to be shaded.

To surround a Block with a shaded Box

Click on the Block.

Select the Surround menu item.

Select Box.

Configure the “Box” Properties dialog by selecting shade from the drop-down list for the filltype field. (See Box Properties for detailed field descriptions.)

Click OK.

Select how much of the content is to be included within this Box.

Click OK.

Spruce then adds the Box to the tree with all the selected content within it.

Likewise, you can decide to remove a surrounding object, such as to remove a Box from around a set of Blocks.

To remove a Box from around a set of Blocks

Click on the Box.

Select the Remove Surround Object menu item.

The Remove Surround Object menu item will remove this object, leaving the content inside intact.

Objects that are allowed to surround other objects vary by what type of object is selected.

If a complex Block is configured, and then later you realize that the Block might overflow, you can use the Surround operation to surround this Block with a Pages object, which will place this Block within the Body of the Pages object. You can then add Headers and Trailers as needed.