A Lesson in Templates for Adobe Acrobat

By Dave Wraight, AcroTips
Visit AcroTips Web site

3 February 2004

1.1. INTRODUCTION

Although Templates have been around since version 3 of Acrobat there was never any really useful supporting information or technical documentation to make use of them. Version 5 and 6 of Acrobat changed all that making it possible to take full control of Templates to create truly dynamic PDF documents.

So what exactly is a Template? A Template is any marked page in a PDF whose form fields and other elements (graphics, text etc) can be added to another page in a PDF or even to an existing page in the PDF. A Template can be made initialy visible or hidden depending on your requirements.

One thing to keep in mind is that Templates are only available in the full versions of Acrobat or inside Adobe Reader with Form Rights enabled.

By using Templates you are able to build a customised PDF document for each user, this customisation can be based on choices made by the user in the PDFor by a pre-determined flow that you have specified.

The decision to use a Template as opposed to dynamically creating form fields can be a difficult one. The best way I have found to make this decision is to work out what you gain by using Templates.

If your page has a lot of form fields, showing/hiding each form field can be very tedious and also very time consuming. By using Templates you can easily append the form fields to a particular page in the PDF document or create a brand new page with just that Template -- and in one action.

Another more useful feature of Templates is that everything that exists on the Template is made visible -- not just the form fields. For example, if you had your company logo and the standard address details etc, this information would also be shown when the Template is used. Achieving this with showing/hiding form fields is something that is much harder to do (if not impossible).

What about the down side? With everything in today's modern software there's always a trade-off between features and functionality. Templates are no exception, the biggest down side to using Templates is that you may find yourself asking how do I get rid of a page I've created? Well the answer is that you can't. This means you need to plan carefully how you implement and use your templates.

The perfect use of a Template is a company expense form, let's say for example you've been away for months and you have hundreds of expenses to put in. Obviously they wont all fit on one page so with a little bit of help from Templates we can simply create more pages in the PDF to accommodate the extra expenses.

1.2. GETTING STARTED

So how do we get started? Generally speaking there are four main steps to using Templates:

  1. Design your Page in your authoring package of choice and convert to PDF
  2. Create Form Fields on top of page
  3. Designate the page as a PDF Template
  4. Use Javascript to create copies of the template ('spawn' the template)

Once you have created your template shell the next step is to define the form fields in the appropriate places. Normally when we create form fields the name of the field isn't that important, however when we are using Templates we have to consider how we will reference our form fields when they have been spawned onto other pages in the document.

As luck would have it, Adobe have also considered this exact scenario and as we'll see in a second they have given us a really easy solution to the problem.

1.2.1. REFERENCE FIELDS ON SPAWNED PAGES

When you spawn a template into a new page or onto an existing page we need to know what the name of the form fields are so we can gain access to them programmatically (using Javascript).

Normally it's not a problem as we can use the normal javascript code: this.getField("row1.date");

However if we have spawned many pages from the same Template we could potentially have the field 'row1.date' on many pages -- how would Acrobat/Javascript know which field we meant when we asked it?

Well Adobe make it easy for us, when we spawn a new page from a Template Acrobat automatically renames the fields to match both the name of the Template and also the page that they have been spawned onto. For example if we create a new page with a Template named 'tpltExpenses' and the page that is created is page 5 our form fields would be named:

P4.tpltExpenses.row1.date

Note: The Page numbering in Acrobat actually starts at 0, ie. the first page in a PDF when talking in Template terms is actually page 0, this is why page 5 is actually P4.

1.2.2. SPAWNING A TEMPLATE

The process of utilising a Template requires a little bit of Javascript to 'spawn' the content from the Template onto existing pages or new pages, so don't be put off if Javascript isnt your thing. To prove how easy it is this is the main piece of Javascript you need to 'spawn' a template (2 z var expTplt = getTemplate("tpltExpenses"); expTplt.spawn(0,false,true);

1.2.3. PUTTING THE PIECES TOGETHER

I've designed a expenses form (using PowerPoint!) to illustrate using Templates (Step 1). Once PDF'd we can now add the form fields in Acrobat (Step 2.), we also need to add a button to allow the users to 'spawn' another blank expenses form. Then all that's left is to mark the page as a template (Step 3).

The button that 'spawns' pages contains the Javascript. Here's how we add that Javascript.

[Part of Step 2.]

  1. After you've drawn the form field button, access the Properties Dialog (Right-Click, Properties or CTRL+E / Properties Bar).
  2. We need to select the Actions Tab, and Select 'Run A Javascript' as the Action Type
  3. Choose 'Mouse Up' as the Event Trigger and Click 'Add'

Now all we need to do is enter our Javascript:

var expTplt = getTemplate("tpltExpenses");
expTplt.spawn(numPages,true,false);

1.2.4. UNDERSTANDING THE JAVASCRIPT

So what exactly does this mean? Line 1 of our code obtains an 'object' that represents the Template we have marked (we haven't actually marked our template yet, that's next in Step 3).

Once we have an object, we can ask it to do things for us, this is what Line 2 is asking for. At Line 2 we ask the template object to 'spawn' itself onto another page, in our case we want it to 'spawn' onto the last page of the PDF.

Because 'numPages' builtin Javascript property returns a page count starting at Page 1, it means a page count of 4 would mean the PDF has pages 0 -- 3, so therefore the 'spawn' will insert a new page into the PDF since there is no page 4 in this document.

The next bit of information we had to specify was if we wanted Acrobat to rename the fields when pages were spawned, in our case we do so we entered 'true'. The next part was if we wanted the 'spawn' to be part of the existing page, it's here that we actually want to insert a new page, so we have to say 'false'.

If you didn't understand a word of that it's okay, just appreciate the two step process we went through: Get the template object, ask it to 'spawn' itself somewhere.

1.2.5. CREATING AND MARKING THE TEMPLATE

For Step 3 we need to flag this completed page as a Template. Follow these steps to create a Template from the current form page.

  1. Choose 'Forms' from the 'Advanced' menu and select 'Page Templates'.

  2. Type a name for this Template, remember it has to match the Javascript name we used, which was 'tpltExpenses' (case sensitive) and click the 'Add' button.

That's it! When you press the 'Add Blank Page' button a new page will be added to the PDF document!

1.2.6. SUMMARY

Easy right? If you stick to the four steps it really is a straight forward process to use templates, and believe me they are extremely versatile and a practical solution to many form based problems.

The Expenses Form is completely unlocked and open for editing and viewing so you can see exactly how it came together. I've also added a little more javascript to the form to total up all of the expenses amounts :).

Good luck!

PDF In-Depth Free Product Trials Ubiquitous PDF

Debenu Aerialist

The ultimate plug-in for Adobe Acrobat. Advanced splitting, merging, stamping, bookmarking, and link...

Download free demo

Debenu PDF Tools Pro

It's simple to use and will let you preview and edit PDF files, it's a Windows application that makes...

Download free demo

Back to the past, 15 years ago! Open Publish 2002

Looking back to 2002, it's amazing how much of the prediction became a reality. Take a read and see what you think!

September 14, 2017
Platinum Sponsor





Search Planet PDF
more searching options...
Planet PDF Newsletter
Most Popular Articles
Featured Product

Debenu PDF Aerialist

The ultimate plug-in for Adobe Acrobat. Advanced splitting, merging, stamping, bookmarking, and link control. Take Acrobat to the next level.

Features

Adding a PDF Stamp Comment

OK, so you want to stamp your document. Maybe you need to give reviewers some advice about the document's status or sensitivity. This tip from author Ted Padova demonstrates how to add stamps with the Stamp Tool along with related comments.