PDF In-Depth

Time for an Acrobat JavaScript Test

January 07, 2002

Advertisement
Advertisement
 

Test your knowledge of Acrobat JavaScript

People ask me all the time what's the best way to learn Acrobat JavaScript. With any other programming language, I would say that a beginner can learn quickest by studying other people's code whenever the opportunity arises. But with JavaScript, I frankly cannot (in good conscience) recommend this, because most of the JavaScript one encounters in the real world is, in my experience at least, scandalously bad, a frightful catalog of things-not-to-do.

The best way to learn Acrobat JavaScript is to spend 20 or 30 minutes a day experimenting in the console. Hit Control-J or Command-J, type something in the console, then select what you typed and click Enter on the numeric keypad. This will execute your code in real time and show the evaluation result in the console. You can execute any AcroJS method this way, and Acrobat will respond to your code instantly. For example, if you execute app.addMenuItem() in the console (supplying appropriate argument values, of course), you can add a menu command to any menu, on the spot. You can also generally get help for an API method by supplying "?" (with quotes) as an argument and executing the method in the console.

The quiz below covers some interesting "console one-liners" that have taught me quite a bit about Acrobat JavaScript over the last six months or so. See how many of these items you can figure out just by looking at them. Allow 15 minutes to work through the 20 questions. Score yourself according to the answers given at the end. (Note that many of the questions involve methods and properties that are available only in Acrobat 5.0 or up. Also note that each code statement is executable exactly as shown.)?

Explain what each statement does and what will appear in the console if you execute the code there:

  1. app.getPath()
  2. ++this.pageNum
  3. 'openDoc' in app
  4. app.activeDocs.length
  5. this.getAnnots()[0].opacity = 0.6
  6. path.split("/").pop()
  7. app.addMenuItem({cParent:"Tools",cName:"-",cExec:""});
  8. for(k in app)console.println(k)
  9. external
  10. path
  11. spell.checkWord("shrek")
  12. Matrix2D
  13. producer
  14. color.toSource()
  15. getField('t1').textFont = 'Verdana'
  16. app.focusRect=false;
  17. app.newDoc()
  18. bookmarkRoot.children[0].color=color.red
  19. global.toSource()
  20. addAnnot().type="Circle"

Answers

  1. This (undocumented) call returns a string containing the device-independent path to the Acrobat folder on your hard drive.?

  2. Preincrementing the Doc property pageNum causes the current page view to switch to the next page. Note that the parent designator 'this' is optional. The default parent object for a property (if you don't specify one explicitly) is always 'this', so leaving 'this' off of Doc-object methods and properties is totally acceptable as long as you have a document open already.

  3. 'openDoc' in app evaluates to true. It tests the existence of a property (openDoc) in a given object (app). Since there is a method on the App object called openDoc(), the statement is true as written. (Methods are simply properties that point to functions.) The "this in that" syntax works because java-scripts "for/in" looping construct uses it on a per-iteration basis.

  4. app.activeDocs.lengthmore information."

  5. this.getAnnots()[0].opacity = 0.6< sets the opacity of the document's first annotation to 60%. It's undocumented and (of course) applies to Acrobat 5.0+ only.

  6. path.split("/").pop()< returns the name of the current file (such as "AcroJS.pdf"). The String method split() simply breaks path into an array, using the forward slash as a delimiter. The Array method pop() returns the last member of the array.

  7. app.addMenuItem({cParent:"Tools",cName:"-",cExec:""})< adds a separator bar to the bottom of the Tools menu.

  8. for(k in app)console.println(k)< dumps all App object property names to the console.

  9. external returns a Boolean value indicating whether whether the current document is being viewed in the Acrobat application or in an external window (such as a Web browser).

  10. path returns a string containing the fully qualified, device-independent path to the current document.

  11. spell.checkWord("shrek")< spellchecks the given word (in this case "shrek") against the default dictionary and returns null if the word is spelled correctly. If the word is not in the dictionary, you'll get back an array of suggested replacements. In this example, we get back: shriek, shrike, shred, shark, shirk, shrug, shrewd, creek, creak, shroud, shared, shored, shard, shirt, short.

  12. Matrix2DAnnots.js (look in your Acrobat/Javascripts folder). It's a general-purpose routine for transforming coordinate systems. You will see the full source code if you simply type "Matrix2D" in the console and hit Enter.

  13. producer tells you what kind of application generated the current document: for example, "Acrobat Distiller 5.0 (Windows)".

  14. color.toSource()< will return (as one big string) the source code for the "color object," which is actually defined in AForm.js (look in your Acrobat/Javascripts folder).

  15. getField('t1').textFont = 'Verdana'< will set the font for your "t1" text field to Verdana, assuming your document has a form field named "t1" and the current system has Verdana in its font collection. The good news is that with Acrobat 5.0, you can finally use any available font in your text fields. The bad news is that you have no way of querying the host system to find out which fonts are actually available, and if your user doesn't have the specified font, he'll see a disturbing message when he tries to type something in the text field, along the lines of:

    Processing Error Message

    This is an ugly situation that Adobe needs to address pronto. Ideally, a font enumeration (in an array property on the App object) should contain the names of available fonts so that runtime discovery of fonts is possible. Failing that, the Field object should have a setTextFont() method that returns a meaningful error value.

  16. app.focusRect=false< will turn off that ugly faint dotted line inside a button when the button has focus.?

  17. app.newDoc()<, with no argument values, will create a new, blank, single-page 8.5x11 document and bring it to the front.

  18. bookmarkRoot.children[0].color=color.red< instantly changes the first bookmark's color to red.

  19. global.toSource()< will hand you a string containing the names and values of all currently defined global variables, including functions (if any).

  20. addAnnot().type="Circle"< adds a new Circle annotation, of diameter 100 pixels, to the lower left corner of the first page of your document.

This quiz covers an enormous amount of ground, and the answers (admittedly short) deserve more elaboration than space here permits. For now, let's just say that a little experimentation in the JavaScript console yields enormous enlightenment.

If you got more than half of these problems right without looking in AcroJS.pdf or "cheating a little" in the console, you can consider yourself a dangerously knowledgeable practitioner of the scripting arts. May your children inherit your methods.

If your acquaintance with Acrobat 5.0 scripting methods is merely casual, getting more than five questions right means you're well on your way to becoming a deviously resourceful Acrobat JavaScript programmer. (Even if you got no questions right, you shouldn't feel bad. This was an extraordinarily challenging quiz.)

Whatever your score, I hope you learned one or two things and discovered a ripe area or two (or five, or ten) for further exploration.

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

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.