Indesign Scripting Object Model

Question

Hi,
Is there some reference documentation that provides detailed information on the Indesign object model as exposed to the scripting interface (javascript)?
I have done fair amount of scripting in Illustrator so I was looking for the Indesign equivalent of this document
http://wwwimages.adobe.com/www.adobe.com/content/dam/Adobe/en/devnet/pdf/illustrator/scrip ting/illustrator_scripting_reference_javascript_cs5.pdf
I looked at this document but it seems kind of sparse (compared to illustrator)
http://wwwimages.adobe.com/www.adobe.com/content/dam/Adobe/en/products/indesign/pdfs/InDes ignCS5_ScriptingGuide_JS.pdf
Obviously they are different applications but I was kind of hoping there would be more info for Indesign scripting.
In particular I am looking for some insight on how to effectively walk or traverse the document structure of an indesign document using code.
Finding specific things by type seems out of the picture becuase after doing object reflection on all the page items in an indesign document nothing seems to have a "type" property.
In my illustrator scripts I was able to place stuff in illustrator layers, give arbitrary pageitems a name and then later go find and manipulate via script. Not as clear how to do this in an indesign context.
The one advantage of this was that in illustrator I was able to use textframes to hold variable data and read later via scripts. The document becomes the database. And I could create any number of arbitrary "variables" inside the document outside the white board. WOndering how to do this kind of stuff with indesign so I can do template driven documents that are managed by scriptings and form UI that I create.

Answer 1

commnet: Glad to hear you're clear on the new keyword. It's something that a lot of people are confused about.
Also glad to hear you've read Crockford's book on this stuff. Honestly I think for most InDesign usage, it's a mistake to worry about any kind of inheritance...usually it's easier to ignore all that stuff.
And to answer the question about number of properties, probably talking max 100 or so. Certainly not thousands. I just want to have my own datastructure embedded in the indesign document that I can easily talk to via scripts. And this data needs to persist between instances of the javascript script's lifecycle. So it seems having some XML to parse is the solution. If that makes sense.
If there was a way to deal with JSON data "hidden" within an indesign document I would gladly work with that. But I still need to change certain common content snippets inside the flow of the indesign document in a consistent way.
I think if you have max 100 properties, you should probably choose the methods that are clearest code, rather than most efficient. I suppose you might have noticable delay with 100, though, obviously try it and see. I'm confused but I thought you needed to have your data associated with text elements inside your document, such that it is visible to a user in the user interface. Hence the proposal of using XML tagged text inside a Text Frame. Did that requirement go away?
If you just want to hide JSON in the document, then use document.insertLabel() of a string of JSON and be done with it.
You can also use the JavaScript interpreter's E4X features, that give you much richer Javascript bindings for manipulating XML objects and files. Unfortunately the Javascript's XML bindings have nothing to do with the InDesign XML object model. So could, e.g., export the InDesign DOM XML into a file, read that into a Javascript XML object, manipulating with E4X functions, write it out to a file, and then re-import it into the DOM. Not really very convenient.
I honestly don't know much about Javascript for browsers, so if you could be more concrete in your queries it would be easier to answer.
Looking forward to your example snippet though.
OK, so, in Jeff (absqua)'s example, you create a constructor for a changeNumber rule, you call the constructor to make a rule, add the rule to the ruleset, and change a value attribute of the rule, and then process the ruleset.
This strikes me as...extremely goofy. For two reasons, first the ruleset creation function should be parametrized with the value you want to change, and second, that you go change the rule's attributes after you have added it to a ruleset. Also, while this works in this example, I don't think it's appropriate to have the xpath attribute hardcoded in the rule creation function -- it's much plausible that you want a function that constructs a rule that changes some arbitrary tag to some arbitrary value.
So, anyhow, if you were going to stick with the constructor paradigm, then I would change from:
var changeNumber = new ChangeDocumentNumber();
var ruleSet = [changeNumber, changeDescription];
changeNumber.value = "5678";
__processRuleSet(doc.xmlElements[0], ruleSet);
to:
var changeNumber = new ChangeDocumentNumber();
changeNumber.value = "5678";
var ruleSet = [changeNumber, changeDescription];
__processRuleSet(doc.xmlElements[0], ruleSet);
But I don't like this, because it's not parametrized reasonably. I would want something like:
var changeNumber = new ChangeValue("//DocumentNumber", "5678");
var changeDescription = new ChangeValue("//DocumentDescription", "New descr.");
var ruleSet = [ changeNumber, changeDescription ];
But because of my disdain for classical inheritance in JavaScript, I would instead write it as:
function changeValue(xpath, newValue){
  return {
    name: "ChangeValue",
    xpath: xpath,
    apply: function(Element, processor) {
      if (newValue) {
        element.contents = newValue;
      return true;
var changeNumber = changeValue("//DocumentNumber", "5678");
var changeDescription = changeValue("//DocumentDescription", "New descr.");
Because I think that a lot clearer about what is going on without introducing confusion.
Edit: removed "this.value" from the above and just used newValue directly.
But if you're defining a lot of rules with different apply functions, this is a very cumbersome strategy. You have all this boilerplate for each function that is basically the same but the apply function is different. This is leads to a lot of wasted code duplications. Why would your apply function be different? Well, that would usually be if you are writing functions that move around XML elements within the document hierarchy, or other things that are not simply changing the value of an element.
I would much prefer to write this as:
var changeRule = makeRule("change",
  function(element, ruleProcessor, newValue) {
    element.contents = newValue;
var changeNumber = changeRule("//DocumentNumber", "5678");
var changeDescription = changeRule("//DocumentDescription", "New descr.");
var ruleSet = [ changeNumber, changeDescription ];
This kind of syntax makes it much more compact to create arbitrary rules with different apply functions. In retrospect, the makeRule() function is named wrong, because it returns a function that makes a rule. Perhaps it'd be more reasonable if it was called makeRuleMaker().
Anyhow, the downside is that the makeRule() function is kind of heinous. I wrote this in March in Re: How to shift content with in cell in xml rules table. But:
//// XML rule functions
// Adobe's sample for how to define these is HORRIBLE.
// Let's fix several of these problems.
// First, a handy object to make clearer the return values
// of XML rules:
var XMLmm = { stopProcessing: true, continueProcessing: false};
// Adobe suggest defining rules constructors like this:
//   function RuleName() {
//       this.name = "RuleNameAsString";
//       this.xpath = "ValidXPathSpecifier";
//       this.apply = function (element, ruleSet, ruleProcessor){
//       //Do something here.
//       //Return true to stop further processing of the XML element
//       return true;
//       }; // end of Apply function
// And then creating a ruleset like this:
//   var myRuleSet = new Array (new RuleName, new anotherRuleName);
// That syntax is ugly and, and is especially bad if
// you need to parametrize the rule parameters, which is the only
// reasonable approach to writing reasonable rules. Such as:
//   function addNode(xpath, parent, tag) {
//       this.name = "addNode";
//       this.xpath = xpath;
//       this.apply = function (element, ruleProcessor) {
//           parent.xmlElements.add(tag);
//           return XMLmm.stopProcessing;
// and then creating a ruleset like:
//   rule = new Array (new addNode("//p", someTag));
// So instead we introduce a makeRule function, that
// allows us to leave behind all the crud. So then we can write:
// addNode = makeRule("addNode",
// function(element, ruleProcessor, parent, tag) {
//     parent.xmlElements.add(tag);
//     return XMLmm.stopProcessing;
// and use:
// rule = [ addNode("//p", someTag ];
function makeRule(name, f) {
    return function(xpath) {
        var
            //xpath=arguments[0],
               // "arguments" isn't a real array, but we can use
               // Array.prototype.slice on it instead...
               args=Array.prototype.slice.apply(arguments, [1]);
        return {
            name: name,
            xpath: xpath,
            apply: function(element, ruleProcessor) {
                    // Slice is necessary to make a copy so we don't
                    // affect future calls.
                var moreargs = args.slice(0);
                moreargs.splice(0, 0, element, ruleProcessor);
                return f.apply(f,moreargs);