See this article about recommended version of Open Office and Libre Office for creation and Editing of templates Recommended Office Versions

Blue Prairie Forms uses normal OpenOffice (or Libre Office) documents as a template to create final documents. Template files are normal OpenOffice documents in most respects but they also contain specialized text snippets called placeholders (aka “tags”). Placeholders are generally unique words, often prefixed with odd characters to make them unique within the document. These placeholders are used to mark locations within a document where real-time data from a transaction should be placed. We call these placeholders ‘tags’.

It is important to understand the terms TAG and VALUE. Tags are simply short names that are associated with dynamic text. If you are familiar with the operation of mail merge functions within word processing products, you already understand tags.

Placeholder / Tagging Practices

Using mail merge as an example, you might write a word processing template that looks like this:

Sample Template File

Dear ~customer,

Thank you for your purchase of ~product on ~date.

We look forward to serving you in the future.

Sincerely,

John Galt

President

Sample Transaction Data

The template contains the following tags ~customer. ~product and ~date. In mail merge, these words are generally column names from a spreadsheet or database.

An example might look like this:

customer	product	date
Dagny Taggart	Rails	04/10/16
Jim Taggart	Toy Trains	04/10/16
Wesley Mouch	Lobotomy	04/10/10

A Sample Finished document

Dear Wesley Mouch,

Thank you for your purchase of Lobotomy on 04/10/10.

We look forward to serving you in the future.

Sincerely,

John Galt

President

When the mail merge is started, the program iterates through the rows in the above table. It will produce three documents and the last document will look like the Sample Finished Document above.

Be Unique

Tags can be any text you wish but care should be taken to ensure that they will not inadvertently clash with words that will be used as static elements of your template. For example, if you use 'customer' as a tag and then create a template that includes the paragraph

“We will be offering 10% to all of our customers”

then when you generate the final document, the paragraph would be changed to:

“We will be offering 10% to all of our Wesley Mouchs”

In order to avoid situations where normal static text is inadvertently replaced by a tag value, it is a good idea to use a tag naming convention that prevents these types of collisions. For example, if you use use the tag “%customer%, instead of “customer', you'll be in good shape because the chance of %customer% occurring in casual text is very remote.

I believe it is also a good practice to always end the tag with a special character. This prevents possible collisions between ambiguous tags. Consider what would happen if we used the following tag names.

Tag Name	Value
%customer	Taggart Transcontinental
%customer_address	123 Taggart Avenue

If we then created a template that looked like this:

Dear %customer,

We see your address is %customer_address.

And then we rendered the template to a final document, we would end up with:

Dear Taggart Transcontinental,

We see your address is Taggart Transcontinental_address.

This is because the rendering engine will first go to the first tag in the table above and replace all instances of %customer with Taggart Transcontinental. This causes the second tag “%customer_address” to be altered in the final document. The second tag becomes “Taggart Transcontinental_address”. So then when the rendering engine processes the second tag, it looks for %customer_address in the template and does not find it because it has already be changed.

Using the above example, consider what would happen if you simply ended the tag name with a % sign. This would prevent the ambiguity and would cause the document to be rendered as expected.

Percent (%) is a character that is often used in UNIX scripts and the author has adopted it to use when naming his tags. However, anything that allows the tag to be unique and non-ambiguous can be used. Blue Prairie Forms does not place restrictions on the characters use in a tag (below Hex FC). However, we highly recommend that you only use tags that:

Tag characters to avoid

Do not include control characters
Are 7-bit (lower than ascii 128)
Do not include unix demon characters
Do not include lf, cr or tab (see rule 1 above)

OpenOffice Template Design Considerations

Microsoft Word

Most users are familiar with Microsoft Word. The techniques used in Word and OpenOffice are similar enough to allow you to become productive in Open Office quickly but different enough that it can be a little frustrating when you first start using Open Office. The frustration comes from being within a document editor that feels very much like Word but then experiencing differences in terminology, menu layout, etc. that make it necessary to ‘think’ when in Microsoft Word these actions are automatic.

Warning: The tag within the template contains formatting markup

You may find that your tag name appears in your template and that you are certain that you have assigned it a value in your host program and let it still the tag remains in the final document rather than being replace with its assigned value. This can happen if you have inadvertently injected market into the tag.

Example:

%myTagName%

In this example, you'll observe that the letters %my are in red while the TagName% ending is in black. For the system to be able to understand that the first part is red and the last part is black, it must place special markup within the string %myTagName% when it stores the tag within the document.

To explain, it might internally store the above with markup like this:

<setColor=red>%my<setColor=black>TagName%

So then, the tag %myTagName% does not really exist because the markup being used has changed the tag name to something other than what is visible in the template. Without the tag name being one coherent, unbroken piece of text, the routine while replaces tags with values would be prevented from finding the tag and replacing it with the proper value.

To remedy

To remedy this situation, you may edit the template and verify that the tag contains no hidden markup by following this procedure:

Triple click to select the entire tag
From the Open Office / Libre Office menumenu, choose Format > Clear Direct Formatting
Now, triple click to select the entiire tag
With the entire tag selected, you may apply justification, color, font, font-size etc. to the entire tag

By Applying the formatting to the entiire tag, rather than to a part of the tag, you will ensure that the entire tag string is preserved as one, coherent, unbroken text string and this should allow the tag to function as expected.

Caveat Emptor

It can be tempting to initially design templates for Blue Prairie Forms using Word rather than Open Office. Indeed, it will save time initially but you will find that incompatibilities between the two products may lead to wasted time and/or odd behavior especially for more advanced forms that use features such as auto page numbering, section breaks, etc.

It is worth the effort spend a few moments to familiarize yourself with Open Office and to refrain from using Word to edit Blue Prairie Forms odt templates.

Open Office Primer

A few minutes spent reviewing the sections below will give you a good understanding of how to properly construct an Open Office odt template from scratch and to avoid frustration when transitioning your form creation skills from Microsoft Word.

Powerful and Flexible but Technical

Open Office is said to be more powerful and flexible than Microsoft Word. It is also said to be more oriented towards the technical mind. Microsoft Word attempts to cater to the non-technical user allowing a more intuitive way to dealing with document elements such as footers, headers, breaks, and styles. All of this is true but with a little time invested by reading this section of the document, the transition to Open Office’s way is an achievable goal for even non-programmers.

A Word about Style

If you are familiar with the use of styles and have incorporated them into your document creation practices in Word, then you will find this transition easier than for those who have not used styles previously.

What is a style?

A style is simply a collection of ‘settings’ that are given a name. This provides a handy way to ascribing certain settings to paragraphs, pages, characters and other elements within a document without having to manual change options for each element separated.

For example, you could create a paragraph style called “quote” that sets the font, font size, font emphases, color, space between lines and even ruler settings. Now, when writing a document, instead of having to make all these adjustments each paragraph that is a quote, you can instead simply select the paragraph then apply the “quote” style to it.

Page Style

As a Blue Prairie Forms template designer, you’ll often face the challenge of converting an existing multi-part form to a laser form. Part of the function of a multi-part impact form is that each layer of the multi-part form denotes a specific flow within the business process. For example it’s common in multipart forms to have three copies; top/white is “Customer Copy”, middle/pink is “Office Copy”, bottom/blue is “billing copy”. Over time, business work flows are developed whereby workers understand to hand the white copy to the customer then burst and separate the office and billing copies based on color and enter them into the appropriate ‘flow’ within the company for processing and filing.

When moving to laser forms, we don’t have multi-parts or color coding so we need to simulate this by printing multiple copies of the form and by marking each copy we print in a special way so that it can be readily identified by the worker (e.g., office copy, customer copy, billing copy). This marking can be accomplished by developing a template that repeats itself across multiple pages and uses elements such as watermarks, or special notations to identify each repeating copy within the template for a particular purpose.

Using the example above, we may wish to create our template so that page one is the Customer Copy, page 2 is the customer copy and page 3 is the billing copy. When the final document is generated from the template, the laser printer will print one print jobs consisting of three copies within the same document.

Illustration showing one template document with three pages; one for each copy. At run-time, one document is generated and one document is printed but depending on the size of the data inserted into the template, each page of the template may become one or more pages in the final document. By using proper form design practices, Blue Prairie Forms will automatically handle this requirement and will also perform many routine form tasks such as auto page numbering, etc.

Placing multiple copies within the same template file offers a number of advantages. Fewer print jobs are generated and have to be processed. If sending to a PDF printer for storage, all copies are contained within one document.

At the time we create templates, we do not know what data may be inserted into the document at runtime. Therefore, each ‘copy’ may end up being one page or more. Yet it is important that we apply the correct watermark for each copy regardless of how many pages that copy becomes.

Page styles in open office allow us to assign a specific header, footer and watermark to each ‘copy’ of the document. If we properly use Page Styles, then Open Office will automatically apply the correct watermark to each copy. Another advantage is that we may wish to have Open Office automatically number the pages within each copy. For example, if we end up with a final document where each copy is three pages and there are three copies, our total page count will be nine pages. By default, if we use Open Office’s automatic page number field within our template and we do nothing special, then the first copy will contain page number 1,2,3 and the second copy (customer copy) would contain the page numbers 4,5,6. Obviously this is not desirable as we would want the page numbering to restart with page 1 when switching to the customer copy so that instead of page numbering like this: 1,2,3,4,5,6,7,8,9 we would instead prefer to see page numbers sequenced as 1,2,3,1,2,3,1,2,3

All of this is easily done with the use of Open Office page styles and by using proper breaks between each template page to change watermarks and to reset page numbers back to 1 when each new copy is reached.

Form Design: How to Use Placeholder Tags