Learning Centers

Where Should I use Acrobat JavaScript?

October 28, 2004

Advertisement
Advertisement
 

Editor's Note: This article is part of the Introduction to Acrobat JavaScript Learning Center

As we alluded to in the previous article 'What is Acrobat JavaScript' it turns out Acrobat JavaScript (AcroJS) can be used in many places inside both the PDF document and through Acrobat the application.

The Bigger Picture

Actually I tried writing about the smaller picture but the font size was too small so I thought a bigger picture would be easier on the eyes. Before we look at the 'Where Should I use Acrobat JavaScript' it might also be useful to see 'Where Can I put JavaScript'.

AcroJS can be stored in the following places:

  • Application Level
  • Document Level
  • Page Level
  • Form Fields
  • FDF Files

There might be other places that JavaScript can be stored but these are by far the most common places so we'll concentrate on these ones in this article. If you decide to get adventurous there are many other resources in our Developer Learning Centre to help you learn more.

Application Level Scripts

These snippets of AcroJS are stored outside of any PDF file and indeed outside of Acrobat the application. When these snippets are stored in files with a .JS extension and then placed into the appropriate location (C:\Program Files\Adobe\Acrobat x.6\Acrobat\JavaScripts) they will then get loaded ever so nicely by Acrobat.

Pros:
  • Available to all PDF documents and therefore all other JavaScripts at all other levels.
  • Allows updating of your scripts without having to update your PDF's.
  • Easy to disable (simply rename the files' extension to something other than .JS).
Cons:
  • Almost impossible to secure -- anyone will be able to read how bad your code is (err, I mean how good it is).
  • Often requires more support for not-so-competent end users.
  • If your system crashes and you have to reinstall Acrobat you may need to also have the JavaScript(s) reinstalled.
  • Only loaded on startup, so if you make changes to an external .JS you'll need to restart Acrobat.

Document Level Scripts

In the early days this way the primary place of existence for AcroJS, nowadays we are spoiled for choice. Document Level Scripts are stored INSIDE the PDF document, which depending on how you work could be a good thing or a bad thing.

AcroJS at the document level can mean more than one thing:

  • Document Action Scripts: Document Will Open, Document Will Close, Document Will Print, Document Did Print are all events that happen (or can happen) that Acrobat allows you to 'hook into' and do stuff when these events occur.
  • Document Scripts: Not triggered by an event such as document opening or closing but rather can be called by other scripts in other places (i.e., form field or application level scripts).
Pros:
  • Your script goes with your PDF, so there's never a chance you'll forget to package it.
  • Good for storing common tasks or scripts that are repeatedly called; I like to think of these scripts as the main place for central repositories.
  • Makes sense for storing JavaScript for validation of PDF specific form field data.
  • Can respond to events at the Document level (opening, closing and printing).
Cons:
  • If your PDF is large and too cumbersome to send over email it'll make updating the Document Level Scripts quite a chore.

Page Level Scripts

There's actually only two places that you can put your page level scripts, right behind door number one which is Page Open Scripts or door number two: Page Close Script.

Basically whenever either of these two events happen -- that is whenever a page in a PDF document is opened (including when you open the PDF document and it opens up a page) and of course the opposite, when a page in the PDF document is closed.

Pros:
  • Great for when you need something to happen when a page is opened of closed.
  • Useful when you have a movie or sound annotation that you want to start or finish based on the page events.
Cons:
  • You can't respond to other events, only Page related events.
  • Availability of some resources can be limited depending on timing of your page loading etc.

Form Field Level Scripts

You are actually putting JavaScript into the form fields; JavaScript can be of various different flavors and be used for different reasons:

  • Custom Data Validation JavaScript
  • Keystroke Validation JavaScript
  • Action Based JavaScripts
  • Calculation JavaScript
  • and more ...
Pros:
  • You can check the stuff entered into form field by your users
  • Adding up numbers and ensuring the numbers entered are correct is dead simple.
  • Using other scripts contained in other places is easy.
  • The validation for any particular field can be contained in the field, which means it goes with the field wherever it goes.
Cons:
  • You can't access these scripts from other places in your PDF document (at least not easily).
  • If you've got LOTS of fields it can be a real pain to update your broken or out-of-date scripts (unless of course you never make mistakes).

FDF Files

Forms Data Format (FDF) can be used to inject JavaScript into Form Fields and also at the Document Level inside a PDF. This can really make life simple when it comes time to update your JavaScript.

To prevent this paragraph from turning into a story on FDF and its many virtues I'll let you have a gander through our resources sections.

Pros:
  • Solves some of those batch update issues mentioned above
  • Very portable
  • Can be injected into PDF files over the web
  • Easily modifiable
Cons:
  • In most cases it isn't secure (it's plaintext after all)
  • Can be difficult to maintain when you have different PDF's with lots of Form Fields.

    Phew, So Now what?

    If you didn't go and eat your lunch during the last part then you should know a little bit more about some of the places that you can put AcroJS in Acrobat/PDF.

    So the title of this article is (in case you forgot) 'Where Should I use Acrobat JavaScript', and below are some ideas of where we can actually use AcroJS.

    Automation

    This is probably the most likely choice for using AcroJS, you want to be able to automate the tasks that you hate doing, or would rather not be doing because they take so loooong. A good example of this is when you need to set the Document Information for lots of PDF files or rotate the pages in certain documents: automation just makes sense.

    I found that the most useful resource to find out what can be automated using AcroJS is the official JavaScript Object Specification (which can be downloaded here).

    Document Manipulation

    Manipulation -- what on earth do I mean here? Rotating, Deleting and Cropping Pages, Insert Pages from other documents, exporting form field data, connecting to web resources and much, much more.

    Printing

    You can create a little bit of JavaScript that prints out a single (or in batch!) PDF in exactly the way you want. Especially Acrobat 6 which now includes a new printer parameters object to let you control the fiddly little settings that can really take the fun out of printing (ok, so maybe printing isn't that fun).

    Form Field Control

    My favorite use of AcroJS is manipulating Form Fields. You can validate the data inside form fields, create new form fields, spawn brand new pages based on user input, move form fields around on the page.

    Database Connectivity

    Still only available in the full versions of Acrobat (Std/Pro), Acrobat Database Connectivity (ADBC) allows you to talk SQL (Structured Query Language) to any database you like (and even the ones you don't like).

    SOAP

    Simple Object Access Protocol might sound a little complex but it really is a great way to build enterprise solutions using PDF and Acrobat. I've written an introductory article on SOAP titled 'Introducing SOAP', which has plenty of advanced JavaScript for you to digest.

    Optional Content Groups

    Layers are fully scriptable. The full potential of Layers hasn't really been explored, but there are lots of resources available to explain some of the more basic concepts available to you when it comes to Layers and AcroJS.

    What Else?

    Well, actually, we forgot Batch Sequences. This is where you create a sequence of tasks that do lots of things for lots of PDF files (hence the batch part). It just so happens that you can also run a snippet of JavaScript as part of the sequence (or as the only thing in the sequence).

    I would recommend reading the articles by D.P. Story on Batch Sequences; he does an excellent job explaining how to setup Batch Sequences and gives some great ideas on where they can be used.

    Where to from Here?

    To get started, read through the rest of the articles in this learning centre, also it would be a good idea to have a wander and perhaps even read more of the articles referenced at the bottom of this article.

    When you need more specific advice or help, participate in the Forums (of course right after you do a search to see if your question hasn't already been answered before ;).

    More Info

  • PDF In-Depth Free Product Trials Ubiquitous PDF

    Debenu Quick PDF Library

    Get products to market faster with this amazing PDF developer SDK. Over 900 functions and an equally...

    Download free demo

    Two Passwords Are Better Than One: The Low-Down On PDF Security

    For people who don't spend their time looking at PDF files in text editors*, PDF security is a sometimes misunderstood beast.

    For example, those document restrictions that PDF files sometimes have -- no Printing, Content Copying, Page Extraction, etc -- are essentially useless unless the PDF also has a User Password.

    January 09, 2014
    Platinum Sponsor



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

    Debenu PDF Aerialist 11

    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.