JavaScripting InDesign

If you do a search of the JavaScript section of the InDesign CS2 Scripting Reference for the words "object specifier" you'll get 448 hits. Half of them are found in the descriptions of the getElements() method. The other half are in the descriptions of the toSpecifier() method.

So, what are these object specifiers? I confess to having some difficulty explaining what they are in abstract terms. I think of them as dynamic pointers into the object structure of InDesign.

Which begs the question: what is the object structure when it is at home? Isn't the term "object model"? Well, yes, most people speak of the object model all the time, but I see a difference between the model: all the possible ways that objects might related to each other, and the structure: the current set of objects and their interrelationships. The model describes what might happen at some point; the structure reflects what is happening now.

For example, if you have no documents open, the model still includes pageItems, but with no documents for those objects to exist in, the structure includes no pageItems right now. Of course, as you work with InDesign, whether with scripts or with the UI, the structure changes to reflect your actions.

So, an object specifier points at an object in the structure. Well, maybe. It's a little more complicated than that because it might point at an object that doesn't yet exist. Look at this:

myObjSpecifier = app.documents.item("Fred.indd");
if (myObjSpecifier == null) {
  alert("'Fred.indd' doesn't exist, yet.");
}

Assuming you don't have a document named "Fred.indd" open when you run that script, you'll get the alert. Compare that with this:

myObjSpecifier = app.documents.item("Fred.indd");
var myFolder= Folder.selectDialog("Choose a home for Fred.indd");
if (myFolder == null) {exit()}
app.documents.add();
app.documents[0].save(File(myFolder.absoluteURI + "/Fred.indd"));
if (myObjSpecifier == null) {
  alert("'Fred.indd' still doesn't exist");
} else {
  alert("'Fred.indd' exists now.");
}

Run this script, and even though we set the value of myObjSpecifier before the document was created, you get the message that Fred.indd now exists. This is why I call this a dynamic pointer into the object structure. Its value adapts to the moment.

Let's take a look at that toSpecifier() method:

myObjSpecifier = app.documents.item("Fred.indd");
$.writeln(myObjSpecifier.toSpecifier());

Run this in ESTK and you see in the console:

/document[@name="Fred.indd"]
undefined

We can ignore the second line; that's just the result of the script. What's interesting is the first line. That's what an object specifier looks like when it is coerced to text. As you can see, it is a descriptive pointer into the object structure.

If we modify this last script to read:

myObjSpecifier = app.documents.item("Fred.indd");
$.writeln(myObjSpecifier.toSpecifier());
myObjSpecifier

And again run it from ESTK, this time, we see in the Console:

/document[@name="Fred.indd"]
[object Document]

This time, the second line is of interest. The result of our script is an object of class Document. That it doesn't exist (yet) is irrelevant (as far as the ExtendScript engine is concerned).

Let's take this one step further:

myObjSpecifier = app.documents.item("Fred.indd");
myObjSpecifier == null;
$.writeln(myObjSpecifier.toSpecifier());

Hmmm, the result of running this is an eye-opening disappointment. To execute the second statement, the engine has to evaluate the variable myObjSpecifier. And, in this case, because we're running with no document named "Fred.indd", it evaluates to null. Apparently, when that happens, it does more than just evaluate the variable; it resolves it, so it becomes undefined, causing the third line of the script to give the error:

Object is invalid

This leaves me scratching my head a little, making the ability to pre-create object specifiers more than a little dodgy if they are this fragile.

I'll have more to say on this subject as I explore further.