openoverlay getting started guide

OpenOverlay 1.0 Getting Started Guide Authors: Dan Gilbert Ian Whiting

Last Updated: October 23, 2007

OpenOverlay – Getting Started Guide

Technology Services Group, Inc. - All Rights Reserved of 14

Approval/Signoff:

Name Project Role Signature Date Naveen Aggarwal Project Manager

Revision History:

Revision Name Description of Change

Reason For Change

Justification for Change

1.0 10/2007

Dan Gilbert New document New document New document



Table of Contents What is OpenOverlay? .................................................................................................................. 4 Getting Started with OpenOverlay............................................................................................... 4

Overview ..................................................................................................................................... 4 What You Will Need .................................................................................................................... 4

Installing OpenOverlay ................................................................................................................. 4 Configuring the OpenOverlay Environment ............................................................................... 5 Configuring OpenOverlay............................................................................................................. 5

Defining an OpenOverlay Configuration File .............................................................................. 5 Creating an OpenOverlay Configuration File .............................................................................. 6

The OpenOverlay Configuration File........................................................................................... 6 Components of OpenOverlay Configuration File ........................................................................ 7

<overlay-config>.................................................................................................................................... 7 <text-templates>.................................................................................................................................... 7 <text-template> ..................................................................................................................................... 7 <text> .................................................................................................................................................... 7 <overlay>............................................................................................................................................... 8 <restrictions>......................................................................................................................................... 8 <restriction>........................................................................................................................................... 8 <actions>............................................................................................................................................... 8 <action>................................................................................................................................................. 9 <block>.................................................................................................................................................. 9 <text> ...................................................................................................................................................10 <rectangle> ..........................................................................................................................................10 <image> ...............................................................................................................................................11 <barcode> ............................................................................................................................................11 <pdf> ....................................................................................................................................................12

Running OpenOverlay from the Command Line ...................................................................... 12 Command Line Statement Format ............................................................................................ 12

Using Tokens with OpenOverlay ............................................................................................... 12 Tokens as Definable Text ......................................................................................................... 13 Tokens as Restriction Properties .............................................................................................. 13



What is OpenOverlay?

OpenOverlay is a lightweight, open-source textual and graphical overlay tool for PDF documents. It provides streamlined configuration settings (no coding required) and allows great flexibility in applying overlays. It can easily be deployed in a web application, invoked from the command line, or embedded in server software such as Documentum or Alfresco.

Popular uses include…

• Apply letterhead/logo • Display document properties

o Status, Version, Intended use, Author/Dept., etc. • Permissions watermarking • Overlay form responses

Getting Started with OpenOverlay

Overview OpenOverlay follows a powerful four step procedure to create textual and graphical overlays. The process can be summarized as follows:

a) Gathers properties a. PDF properties (page orientation, number) b. Document metadata (dept, author, date) c. Data from invoker (user, role, application)

b) Determines applicable overlays c) Applies and merges overlays d) Produces a seamless PDF

What You Will Need In order to utilize open overlay, you will need the following:

a. A distribution of OpenOverlay b. Java Runtime Environment – version 1.4 or higher. May be obtained at

http://www.java.com

Installing OpenOverlay OpenOverlay is an open-source software initiative provided free of charge by Technology Services Group. The latest distribution of OpenOverlay, as well as other open-source solutions from TSG, may be downloaded at http://tsgrp.com/services_solutions/open-source.jsp. Once you have obtained OpenOverlay, extract the folder to a directory of your choice. The contents of the directory will include two configuration files, the open-overlay.jar file, and a folder containing supplemental .jar files.



Configuring the OpenOverlay Environment

In order to run OpenOverlay, several additions must be made to your machine’s environment. The following paths must be added to you’re the CLASSPATH environmental variable:

1. . (current directory) 2. open-overlay.jar 3. lib/bfopdf.jar 4. lib/commons-lang.jar 5. lib/itext-1.4.8.jar 6. lib/junit.jar 7. lib/log4j.jar 8. lib/spring-beans.jar 9. lib/spring-context.jar 10. lib/spring-core.jar 11. lib/tsgrp.jar 12. lib/xalan.jar

To set the CLASSPATH environment variable: 1. In a command shell, navigate to the directory where your distribution of OpenOverlay

is installed. 2. Execute the following commands:

set CLASSPATH=.;%CLASSPATH% set CLASSPATH=open-overlay.jar; %CLASSPATH% set CLASSPATH=lib/bfopdf.jar; %CLASSPATH% set CLASSPATH=lib/commons-lang.jar; %CLASSPATH% set CLASSPATH=lib/itext-1.4.8.jar; %CLASSPATH% set CLASSPATH=lib/junit.jar; %CLASSPATH% set CLASSPATH=lib/log4j.jar; %CLASSPATH% set CLASSPATH=lib/spring-beans.jar; %CLASSPATH% set CLASSPATH=lib/spring-context.jar; %CLASSPATH% set CLASSPATH=lib/spring-core.jar; %CLASSPATH% set CLASSPATH=lib/tsgrp.jar; %CLASSPATH% set CLASSPATH=lib/xalan.jar%CLASSPATH%

3. These jar files must be included in the classpath for every console you wish to use

OpenOverlay in. If these commands become bothersome, a .bat file may be used to programmatically set the classpath.

Configuring OpenOverlay OpenOverlay provides a highly configurable interface which allows complete control of functionality without the necessity of modifying code. Configuring your distribution of OpenOverlay is a two-step process.

Defining an OpenOverlay Configuration File OpenOverlay applies overlays specified by a configuration file. The name of the configuration file may be set in the openoverlay-spring-config.xml file. In this file, there is a bean definition identified by the name “overlayConfig”. The value of the first



constructor-arg element defines the name of the configuration file that OpenOverlay will use when executed. …

<bean id="overlayConfig" class="com.tsgrp.openoverlay.core.XmlConfigFactory" factory-method="createInstance">

<constructor-arg value="overlay-config-jnj.xml" /> <constructor-arg value="default" />

</bean> …

Figure 1.1 – openoverlay-spring-config.xml – bean which defines which configuration file to use

Creating an OpenOverlay Configuration File After the name of the configuration file has been set in step one, you are ready to create an OpenOverlay configuration file. In your OpenOverlay installation directory, create a file with the name specified in the previous step. OpenOverlay configuration files must be well-formed XML. This file defines templates, overlays, restrictions, actions and elements in order to construct PDF overlays and watermarks. Further details regarding the format and construction of configuration files may be found in the “OpenOverlay Configuration File” section of this guide.

<overlay-config> <text-templates>

<text-template name="default"> <text font-size="12" font-family="arial" font-weight="none" font- style="none" color="black"> default text.</text>

</text-template> <text-template name="date">

<text color="gray">Reference Copy - Printed on ${date} (EST)</text> </text-template>

</text-templates> <overlay id="LetterLegalPortaitFooter">

<restrictions> <restriction key="page.size" value="letter|legal" /> <restriction key="page.orientation" value="portrait" />

</restrictions> <actions /> <block id="1" x="10" y="24" rotation="0" alignment="left" background-color="white" opacity="1">

<rectangle x-offset="592.8" y-offset="778.8" background-color="white" border-width="0.5" />

</block> <block id="2" x="308.4" y="204" rotation="0" alignment="center">

<text template="date" color="white" font-size="26">Watermark</text> </block> <block id="0" x="124.80" y="241.2" rotation="0" alignment="left">

<image file="images/logo.jpg" /> </block>

</overlay> </overlay-config>

Figure 1.2 – Example of a simple OpenOverlay Configuration File

The OpenOverlay Configuration File OpenOverlay uses streamlined settings to define overlays to apply. Understanding the configuration file is the best way to explore the functionality that OpenOverlay presents to users. A valid configuration file is comprised up of valid XML with several constraints.



Components of OpenOverlay Configuration File

<overlay-config>

Parent Element: None; this is the root element. Number of occurrences: 1

Attributes: None Description: This is the document’s root element. All other

elements are descendents of this element.

<text-templates> Parent Element: <overlay-config>

Number of occurrences: 1 Attributes: None

Description: This element acts as a container for all of the file’s text templates.

<text-template> Parent Element: <text-templates>

Number of occurrences: [1 … unlimited] Attributes: name

- required - defines the name of this template

Description: Each of these elements describes a template, which can be referenced from the rest of the configuration file. Each one has one child element, named <text>. Each file must contain one <text-template> element named “default”.

<text> Parent Element: <text-template>

Number of occurrences: 1 per <text-template> element Attributes: color

- optional - defines the default font color of elements

referencing this template font-family

- optional - defines the default font family of elements

referencing this template font-size

- optional - defines the default font size of elements

referencing this template font-style

- optional - defines the default font style of elements

referencing this template font-weight

- optional



- defines the default font weight of elements referencing this template

Text Content: Defines the default text content of elements referencing this template.

Description: This is the document’s root element. All other elements are descendents of this element.

<overlay> Parent Element: <overlay-config>

Number of occurrences: [0…unlimited] Attributes: id

- required - defines a unique name to identify this overlay

with Description: Each <overlay> element represents a distinct overlay

which may be applied to a document. When multiple overlays are applied to the same page in a document, they are applied in the order which they appear in the configuration file.

<restrictions> Parent Element: <overlay>

Number of occurrences: 1 per <overlay> element Attributes: None

Description: This is a container for overlay-specific restrictions.

<restriction> Parent Element: <restrictions>

Number of occurrences: [0…unlimited] Attributes: key

- required - defines a restriction key to use for this

overlay - see CHART 1.1 for valid values

value - required - defines a restriction value to use for the

corresponding key - see CHART 1.1 for valid values

Description: Each <restriction> element represents a restriction to be used when applying this overlay to a document. This allows users to specify this overlay to only be applied to pages in a document that exhibit certain traits (page size, orientation, etc).

<actions> Parent Element: <overlay>

Number of occurrences: 1 per <overlay> element



Attributes: None Description: This is a container for overlay-specific actions.

Note: Actions are not currently implemented.

<action> Parent Element: <actions>

Number of occurrences: [0…unlimited] Attributes: value

- required - defines an action value - see CHART 1.1 for valid values

Description: Each <action> element represents an action to be used when applying this overlay to a document. This allows users to specify this overlay the PDF to be locked, etc.

Note: Actions are not currently implemented.

<block> Parent Element: <overlay>

Number of occurrences: [0…unlimited] Attributes: x

- required - represents the horizontal position of the left-

hand side of the element, in points from the left hand side of a page

y - required - represents the vertical position of the bottom

of the element, in points from the bottom of a page

alignment - defines the alignment of the element - valid for <text> elements only - if not defined, defaults to “left” - if value is “left”, the x attribute value

corresponds to the position of the left-hand side of the element

- if value is “center”, the x attribute value defines the center horizontal position of the element

- if value is “right”, the x attribute value defines the position of right-hand side of the element

rotation

- optional - represents the amount, in degrees, the

element is rotated counter-clockwise about its bottom left corner



- only valid for <text> and <image> element types

opacity - optional - represents the opacity of the element - must be a value between 0 (transparent) and

1 (fully opaque), inclusive Description: Each <block> element represents a screen feature

contained in the overlay. Currently supports element types of text, rectangles and images. Each <block> element may have one child element, either <text>, <rectangle>, or <image>.

<text> Parent Element: <block>

Number of occurrences: maximum of 1 per <block> element Attributes: template

- optional - defines the name of a template to use - value must match the name of a <text-

template> element - if not defined, or not a valid value, the <text-

template> element “default” is used color

- optional - defines the font color of this element

font-family - optional - defines the font family of this element

font-size - optional - defines the font size of this element

font-style - optional - defines the font style of this element

font-weight - optional - defines the font weight of this element

Text Content: Defines the text content of this element.

Description: This represents a textual element on an overlay. Use these elements to overlay text onto an existing document, or to create a watermark.

<rectangle> Parent Element: <block>

Number of occurrences: maximum of 1 per <block> element Attributes: x-offset

- required - defines the width of the element, in points

y-offset - required - defines the height of the element, in points



background-color - optional - defines the color of the rectangle - if not defined, defaults to “white”

border-width - optional - defines the width of the element’s border - if not defined, defaults to “0”

Description: This represents a rectangle element on an overlay. Use these elements to cover existing text on a document, or as a background to make text elements more readable.

<image> Parent Element: <block>

Number of occurrences: maximum of 1 per <block> element Attributes: file

- required - defines a path to an image file

Description: This represents an image element on an overlay. Use these elements to add the specified image file to the overlay.

<barcode> Parent Element: <block>

Number of occurrences: maximum of 1 per <block> element Attributes: type

- optional - defines the type of iText supported barcode

that will be produced. - valid values:

• 39 • 128 • EAN • Inter25 • Postnet • Codabar

- default value is 128. format

- optional - defines the formatting of the barcode that will

be produced. - if formatting and type are not compatible,

barcode will not be generated. - default formatting will be used if not specified.

Description: This represents a barcode element. iText can generate several different kinds of barcodes. There are restrictions on values, types and formats which are evaluated at runtime. If there are incompatibilities, the barcode is not generated. For more information,



please see the iText documentation.

<pdf> Parent Element: <block>

Number of occurrences: maximum of 1 per <block> element Attributes: file

- required - defines a path to a pdf file

Description: This represents a PDF file element, which will be appended on top of the input PDF. All elements from this PDF will be added to pages in the document that utilize an overlay with a pdf node element.

Running OpenOverlay from the Command Line

Command Line Statement Format

OpenOverlay may be invoked from the command shell using this instruction while in your installation directory.

java com.tsgrp.openoverlay.FileSystemOverlayer [input][output][tokens][values]

With the following parameters defined:

a. [input] – specifies the path and name of a PDF file to overlay. b. [output] – specifies the path and name of the PDF file to be generated. c. [tokens] – a comma delimited list of token names d. [values] – a comma delimited list of token values (order must correspond to the

[tokens] parameter)

The input and output parameters gives users flexibility on which file OpenOverlay will overlay, and how it will be saved to your machine. The token list and value list allow the user to specify values for restriction keys and define text token values located in the configuration file.

Using Tokens with OpenOverlay

The following tokens are automatically generated and may be used in text elements and restrictions without definition in the command line:

a. currentPage – The number of the current page in a document b. totalPages – The total number of pages in a document c. page.orientation – The orientation of the current page in a document; either

‘landscape’ or ‘portrait’ d. page.size – The size of the current page in a document; either ‘Letter’, ‘Legal’, or

‘Executive

The values of these tokens may not be overridden from the command line.



When a configuration file contains multiple tokens, the lists of tokens and values must be delimited by commas, and all items containing spaces must be encapsulated within quotation marks.

Tokens as Definable Text

Tokens may be used in configuration files as placeholders for text to be defined at runtime. Text elements and text-template elements may include tokens in the following manner:

${token}

If this token is defined at runtime, the text is resolved and replaced by the corresponding value. For example, if the following element were present in the utilized overlay configuration file,

… <block id="2" x="308.4" y="204" rotation="0" alignment="center">

<text template="default" color="white" font-size="26">${token}</text> </block> …

Figure 1.2 – Example of a text element utilizing a token

and this command was used to run OpenOverlay,

java com.tsgrp.openoverlay.FileSystemOverlayer in.pdf out.pdf token Hello

then, the text element will contain the word “Hello”.

If a text element contains one or more tokens which are not defined by the command line instruction, that element will not be used in the overlay.

Tokens as Restriction Properties

In addition to resolving text placeholders, token name/value pairs may be used to determine the validity of overlay restrictions. Restrictions are overlay-specific elements defined as key/value pairs in the configuration file.

… <restrictions>

<restriction key="page.size" value="letter|legal" /> <restriction key="currentPage" value="1.*" /> <restriction key="customToken" value="Approved" />

</restrictions> …

Figure 1.3 – Example of restrictions using custom and automatically generated tokens.

Restriction key attributes correspond to token names. Restriction value attributes are regular-expressions corresponding to token values. An overlay containing the above restrictions node would only be applied to letter or legal sized pages whose page numbers start with a ‘1’ and when customToken is defined as ‘Approved’.

Multiple restrictions are AND-ed together, thus they must all pass in order for an overlay to be applied to the page. This means that in the above example, the token



‘customToken’ must be defined as ‘Approved’ at runtime in order for this overlay to have a chance of passing all restrictions. If it is not defined, or defined as something else, the overlay will not be applied to any pages in a document. The other tokens are automatically generated by OpenOverlay at runtime.

openoverlay getting started guide

Documents

technology services group

classpath classpath lib spring

comma delimited list

documents root element

openoverlay configuration file

started guide

configuration files

configuration file