I'm going to take a heterodox viewpoint today. Maybe it will provoke somebody to step up, flick their cigaret ash on my shoe, and say "Oh yeah? Here's where you're wrong, dimbulb..." (Then again, maybe not.)
Have we been using the right syntax?
My contention is that we've all been idiots for typing 'this' in front of Doc object properties and methods all these years. (At least, it feels like years...) You know what I'm talking about:
var name = this.getField('name').value;
This is a typical example of the (unnecessary) use of 'this' as an object specifier. We use 'this' on the front of Doc object methods and properties to specify the current document's Doc object. But as opposed to what? Another document's Doc object? Adobe recommends against using any Doc object reference(s) to any remote document(s), for the simple reason that such references can be invalidated suddenly, without warning, if a file closes while the Doc reference is still open. To deal with the "dangling Doc reference" problem, Adobe has come up with publish() and subscribe() methods for Acrobat 5.0 (available now, undocumented, in 4.05).
How to Break Your Pathetic Addiction to 'this'
Get used to the fact that code incorporating Doc-object methods will work just fine without 'this' on the front. Use no object specifier at all. You can just write:
var name = getField('name').value;
Why 'this' Is Dangerous
For a quick example, let's just suppose that we would like to modify the Array class such that there is a new method, rotate(), which moves all array members to the right while popping the last member off and reattaching to the front of the array list. Here's how you could add that method to the root class:
Let's look at this code. What we've done is attach a new method (function) to the Array class using the prototype hook. Our new function has no arguments. It returns the array, with members rotated. The unshift() method adds a new item to the beginning of the array, moving all other items over. The item we're adding, however, is the tail item of the original array. So we've achieved the goal of moving all items over one place while relocating the tail-end item to the start of the array.
After the above code executes, ANY new Array you construct with the Array constructor will have a rotate() method. What's more, your existing arrays will also have that method! It's almost magical.
var n = new Array(1,2,3,4);
var m = n.rotate(); // 'm' is [4,1,2,3]
I'm sure you noticed one peculiar thing about the foregoing code, which is that I used
'this' on the front of the unshift() and pop() methods. Why did I do this?
Because I want to refer to the parent array. I have no reference to it (no arguments were
passed in), so the prototype property lets me get the reference I need by using 'this'.
Inside the rotate function definition, 'this' is scoped to the parent object, not the Doc
Here's how you can get in trouble: If you try a call to this.getField() in the
to be scoped to the function's parent object, not to the Doc object.
What is the solution?
The ONLY way to get any Doc object methods or properties to work properly in the code for
rotate() is to leave off the 'this' specifier.
If you call getField(), completely bare, inside the rotate() function, it will
work. (Ditto for zoom, pageNum, and all the rest.) If you put 'this' on the front, your code
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.