Accessing the InDesign Scripting DOM via Lua

Overview

The InDesign Scripting DOM provides full access to the creation and manipulation of all content within InDesign. By combining this the speed of Lua with the data access and control facilities of EasyCatalog, it’s possible to create data driven content in virtually any format.

Accessing

The InDesign Scripting DOM can be accessed via Lua within Formatting Rules and Script Label contexts. The DOM is accessed by calling the getdom() method of a Frame or Formatting Rule. An optional parameter can be used to specify the object required, the default being the frame type. Options also include Document or Application. For formatting rules we recommend using getdom(“Document”) rather than navigating the hierarchy as there are instances where the rules are placed outside page bounds.

-- access the DOM of a frame
framedom = frame:getdom();

-- access the DOM of the document the frame is in
documentdom = frame:getdom("Document");

-- access the DOM of a frame

framedom = frame:getdom();

-- access the DOM of the document the frame is in

documentdom = frame:getdom("Document");

Once the DOM is acquired, properties and methods are accessed using the same naming conventions as Extendscript. However there are few language related differences:

Properties are functions

To set a property, provide a parameter. To get a property omit the parameter:

-- aquire the DOM
domframe = frame:getdom();

-- set a property
domframe:bottomRightCornerOption("CornerOptions.ROUNDED_CORNER");

-- get a property
value = domframe:bottomRightCornerOption();

-- aquire the DOM

domframe = frame:getdom();

-- set a property

domframe:bottomRightCornerOption("CornerOptions.ROUNDED_CORNER");

-- get a property

value = domframe:bottomRightCornerOption();

Enumeration are strings

Lua does not support typed enumerations. They are implemented as strings as shown the following example. Also notice the use of colors():add() (as properties are functions):

col = document:colors():add();
col:model("ColorModel.PROCESS");
col:space("ColorSpace.CMYK");
col:colorValue( {20,100,100,0} );

col = document:colors():add();

col:model("ColorModel.PROCESS");

col:space("ColorSpace.CMYK");

col:colorValue( {20,100,100,0} );

Compared this to the ExtendScript version:

var myColorA:Color = myDocument.colors.add();
myColorA.model = ColorModel.PROCESS;
myColorA.space = ColorSpace.CMYK;
myColorA.colorValue = [20, 100, 100, 0];

var myColorA:Color = myDocument.colors.add();

myColorA.model = ColorModel.PROCESS;

myColorA.space = ColorSpace.CMYK;

myColorA.colorValue = [20, 100, 100, 0];

Determining object types

The Javascript constructor.name method should be replaced with a string comparison on the object itself. For example:

function tablelength(T)
  local count = 0
  for _ in pairs(T) do count = count + 1 end
  return count
end
app = frame:getdom("Application");

-- 'selection' returns a table of objects. Tables need to be counted in Lua
s =  app:selection();
if tablelength(s) > 0 then
  if tostring(s[1]) == "Rectangle" then 
    -- it's a rectangle!
  end
end;

function tablelength(T)

local count = 0

for _ in pairs(T) do count = count + 1 end

return count

end

app = frame:getdom("Application");

-- 'selection' returns a table of objects. Tables need to be counted in Lua

s = app:selection();

if tablelength(s) > 0 then

if tostring(s[1]) == "Rectangle" then

-- it's a rectangle!

end

end;

Adding an Object With Properties

Some add methods allow the specification of properties. Lua tables can be used where the table entry key is the property name and the value is the value:

framedom = frame:getdom();
page = framedom:parentPage();
frames = page:textFrames();
myframe = frames:add( { bottomRightCornerOption = "CornerOptions.ROUNDED_CORNER", geometricBounds ={72, 72, 190, 190} });

framedom = frame:getdom();

page = framedom:parentPage();

frames = page:textFrames();

myframe = frames:add( { bottomRightCornerOption = "CornerOptions.ROUNDED_CORNER", geometricBounds ={72, 72, 190, 190} });

Working with Collections

Most of the available objects in the DOM have a collection counterpart. Regarded as a class, a collection is nothing but a generic interface giving an easy and ordered access to homogeneous InDesign objects that live together. Collections support the methods add, itemByName, itemByID, item, firstItem, lastItem, middleItem, anyItem, previousItem, nextItem, itemByRange, everyItem.

Accessing a collection is a case of accessing the property containing the collection. If the property method is passed a parameter, this is assumed to be an implied item() call. For example:

-- frame is a text frame, get the DOM:
framedom = frame:getdom();

-- this uses the collection method item to return the nth item
framedom:parentStory():texts():item(0):contents("This is an InDesign story with a table.")

-- can also be expressed by passing the index of the text item to the texts method:
framedom:parentStory():texts(0):contents("This is an InDesign story with a table.")

-- frame is a text frame, get the DOM:

framedom = frame:getdom();

-- this uses the collection method item to return the nth item

framedom:parentStory():texts():item(0):contents("This is an InDesign story with a table.")

-- can also be expressed by passing the index of the text item to the texts method:

framedom:parentStory():texts(0):contents("This is an InDesign story with a table.")

Special Collection Objects

All collections support the everyItem() and the itemByRange() methods. These return a single object containing references to multiple objects of the same type. Properties and methods which are exposed to this object apply to all contained objects. This gives a performance boost as it reduces the number of transactions in the document database. For example:

framedom = frame:getdom();
mytable = framedom:tables():add( { columnCount = 2, bodyRowCount = 2});
t_properties = { fillColor = "Black", bottomInset = "15mm", topInset = "15mm"};
mytable:cells():everyItem():properties(t_properties);

framedom = frame:getdom();

mytable = framedom:tables():add( { columnCount = 2, bodyRowCount = 2});

t_properties = { fillColor = "Black", bottomInset = "15mm", topInset = "15mm"};

mytable:cells():everyItem():properties(t_properties);

In addition to this method of access, an optional false boolean parameter can be supplied to return a table of objects rather than a special collection object:

framedom = frame:getdom();
mytable = framedom:tables():add( { columnCount = 2, bodyRowCount = 2});
table_of_cells = mytable:cells():everyItem(false)
count = 0
for _ in pairs(table_of_cells) do 
  count = count + 1 
end
error(count)

framedom = frame:getdom();

mytable = framedom:tables():add( { columnCount = 2, bodyRowCount = 2});

table_of_cells = mytable:cells():everyItem(false)

count = 0

for _ in pairs(table_of_cells) do

count = count + 1

end

error(count)

Because collections offer a performance boost when setting properties a Collection.new allows the creation of singleton object from a table of objects(of the same type):

framedom = frame:getdom();
mytable = framedom:tables():add( { columnCount = 10, bodyRowCount = 10});

-- populate a table with every other cell
every_other_cell = { }
for i=1,mytable:cells():count(),2 do
   table.insert(every_other_cell, mytable:cells(i-1));
end

-- create a new singleton
new_collection = Collection.new(every_other_cell);

-- set the properties in one command
cell_properties = { fillColor = "Black" };
new_collection:properties(cell_properties);

framedom = frame:getdom();

mytable = framedom:tables():add( { columnCount = 10, bodyRowCount = 10});

-- populate a table with every other cell

every_other_cell = { }

for i=1,mytable:cells():count(),2 do

table.insert(every_other_cell, mytable:cells(i-1));

end

-- create a new singleton

new_collection = Collection.new(every_other_cell);

-- set the properties in one command

cell_properties = { fillColor = "Black" };

new_collection:properties(cell_properties);

Examples

Formatting Rule Post Processing Example to iterate through the frames in a rule:

-- aquire the DOM
dom = formattingrule:getdom();
domdoc = formattingrule:getdom("Document");
blackcolor = domdoc:colors():itemByName("Black");
tbl = dom:allPageItems();
for _,item in pairs(tbl) do 
  if item:label() == "b" then
   item:fillColor(blackcolor)
  end
  item:bottomRightCornerOption("CornerOptions.ROUNDED_CORNER");
end

-- aquire the DOM

dom = formattingrule:getdom();

domdoc = formattingrule:getdom("Document");

blackcolor = domdoc:colors():itemByName("Black");

tbl = dom:allPageItems();

for _,item in pairs(tbl) do

if item:label() == "b" then

item:fillColor(blackcolor)

end

item:bottomRightCornerOption("CornerOptions.ROUNDED_CORNER");

end

Creating a dialog box:

app = frame:getdom("Application");
dlgRef = app:dialogs():add({name = "dlgName", canCancel = true , label = "dlgLabel"});
dlgColumn = dlgRef:dialogColumns():add();
dlgRow = dlgColumn:dialogRows():add();
rGroup = dlgRow:radiobuttonGroups():add();
rGroup:radiobuttonControls():add({staticLabel = "Hi-res_PDF", checkedState = true});
rGroup:radiobuttonControls():add({staticLabel = "Low-res_PDF"});
rGroup:radiobuttonControls():add({staticLabel = "PRINTER"});
ok = dlgRef:show();
if ok == true then error ("ok was pressed") end
Script Label example to insert text and a table into a text frame:

app = frame:getdom("Application");

dlgRef = app:dialogs():add({name = "dlgName", canCancel = true , label = "dlgLabel"});

dlgColumn = dlgRef:dialogColumns():add();

dlgRow = dlgColumn:dialogRows():add();

rGroup = dlgRow:radiobuttonGroups():add();

rGroup:radiobuttonControls():add({staticLabel = "Hi-res_PDF", checkedState = true});

rGroup:radiobuttonControls():add({staticLabel = "Low-res_PDF"});

rGroup:radiobuttonControls():add({staticLabel = "PRINTER"});

ok = dlgRef:show();

if ok == true then error ("ok was pressed") end

Script Label example to insert text and a table into a text frame:

Creating a table and inserting text:

framedom = frame:getdom();
framedom:parentStory():texts():item(0):contents("This is an InDesign story with a table.")
mytable = framedom:tables():add( { columnCount = 2, bodyRowCount = 2});
framedom = frame:getdom();
framedom:parentStory():texts():item(0):contents("This is an InDesign story.")
-- insert a table
mytable = framedom:tables():add( { columnCount = 2, bodyRowCount = 2});
for i=1,mytable:cells():count() do
mytable:cells():item(i-1):texts():item(0):contents("hello" .. i);
end

framedom = frame:getdom();

framedom:parentStory():texts():item(0):contents("This is an InDesign story with a table.")

mytable = framedom:tables():add( { columnCount = 2, bodyRowCount = 2});

framedom = frame:getdom();

framedom:parentStory():texts():item(0):contents("This is an InDesign story.")

-- insert a table

mytable = framedom:tables():add( { columnCount = 2, bodyRowCount = 2});

for i=1,mytable:cells():count() do

mytable:cells():item(i-1):texts():item(0):contents("hello" .. i);

end

Populating Tables with Tabular Fields

In this example, a tabular field is used to populate a prototype table, which is repeated enough times to hold data for each row:

Template frame contains 4 column table with no data:

The Script label on the frame controls population of the data:

function duplicate_table(t)
  myInsertionPoint = t:storyOffset();
  imyInsPointIndex = myInsertionPoint:index();
  myStory = myInsertionPoint:parentStory();            
  myCharThatHoldsMyTable = myStory:characters(imyInsPointIndex);
  myNewTablePosition = dom:insertionPoints():nextItem(myInsertionPoint);
  myCharThatHoldsMyTable:duplicate("LocationOptions.AFTER",myNewTablePosition)
end

data = field('tabular field')
myRowCount = data:rowcount();
tables_needed = myRowCount /4
if myRowCount % 4 == 0 then
tables_needed = tables_needed  -1
end

dom = frame:getdom();
t = dom:tables(0);
for i = 1, tables_needed do
  duplicate_table(t)
end

dom = frame:getdom("TextFrame");

offset = t:storyOffset();
t:cells():length();
table_index = 0;
table_col_index = 0

for row =1,data:rowcount() do 
  cell_content =data:cell(row,1):getcontent()
  dom:tables(table_index):cells(table_col_index):texts(0):contents(cell_content);
  table_col_index = table_col_index + 1
  if table_col_index == 4 then
     table_index = table_index  + 1;
    table_col_index = 0 
 end
end

function duplicate_table(t)

myInsertionPoint = t:storyOffset();

imyInsPointIndex = myInsertionPoint:index();

myStory = myInsertionPoint:parentStory();

myCharThatHoldsMyTable = myStory:characters(imyInsPointIndex);

myNewTablePosition = dom:insertionPoints():nextItem(myInsertionPoint);

myCharThatHoldsMyTable:duplicate("LocationOptions.AFTER",myNewTablePosition)

end

data = field('tabular field')

myRowCount = data:rowcount();

tables_needed = myRowCount /4

if myRowCount % 4 == 0 then

tables_needed = tables_needed -1

end

dom = frame:getdom();

t = dom:tables(0);

for i = 1, tables_needed do

duplicate_table(t)

end

dom = frame:getdom("TextFrame");

offset = t:storyOffset();

t:cells():length();

table_index = 0;

table_col_index = 0

for row =1,data:rowcount() do

cell_content =data:cell(row,1):getcontent()

dom:tables(table_index):cells(table_col_index):texts(0):contents(cell_content);

table_col_index = table_col_index + 1

if table_col_index == 4 then

table_index = table_index + 1;

table_col_index = 0

end

Result when populated:

The technique can also be applied to Formatting Rules, with the advantage of updating if the original data changes.

Accessing EasyCatalog Scripting Functions

With the scripting module installed, it’s possible to access methods exposed by EasyCatalog. The FIELD, DATASOURCE and RECORD objects are automatically converted to compatible types. The following example acquires a FIELD object and then inserts it using the ‘insertField’ method which is added by EasyCatalog to the InsertionPoint class:

-- Get the FIELD object
field = FIELD.get("some field name");

-- -1 is the end of the story
insertionPoint  = frame:getdom():parentStory():insertionPoints(-1);

-- Insert the field 
insertionPoint:insertField(field);

-- Get the FIELD object

field = FIELD.get("some field name");

-- -1 is the end of the story

insertionPoint = frame:getdom():parentStory():insertionPoints(-1);

-- Insert the field

insertionPoint:insertField(field);

Example using Formatting Rule Post Processing Logic to create a table that mirrors the contents of a named tabular field. The Formatting Rule is an empty text box.

framedom = formattingrule:getdom();
field = SELECTION:root():getfield("producto_imgs");
table = field:content();
 mytable = framedom:tables():add( { columnCount = table:colcount(), bodyRowCount = table:rowcount()});
for row=1,table:rowcount() do 
  for col=1,table:colcount() do 
    insertionPoint  = mytable:rows(row-1):cells(col-1):insertionPoints(-1)
    insertionPoint:insertField(field,row-1,col-1);
  end
end

framedom = formattingrule:getdom();

field = SELECTION:root():getfield("producto_imgs");

table = field:content();

mytable = framedom:tables():add( { columnCount = table:colcount(), bodyRowCount = table:rowcount()});

for row=1,table:rowcount() do

for col=1,table:colcount() do

insertionPoint = mytable:rows(row-1):cells(col-1):insertionPoints(-1)

insertionPoint:insertField(field,row-1,col-1);

end

Debugging

In CC 2018 and above remote debugging is supported using the ZeroBrane Studio IDE. Debugging is only available when “Enable Sockets” is set to true in Advanced preferences. Re-launch InDesign to apply this setting. To Debug:
Copy mobdebug.lua and socket.lua into any location checked by the ‘require’ command (A list is shown if the module cannot be found). These are available from the ZeroBrane download.
Launch the IDE. Go to Project | Start Debugger Server and start the debugger server (if this menu item is disabled, the server is already started)
Add the following to your script:

require('mobdebug').start()

1	require('mobdebug').start()

Test your script. You should see a green arrow pointing to the next statement after the start() call in the IDE and should be able to step through the code.

What is a Matrix Table? Custom Menus and Dialogs

Accessing the InDesign Scripting DOM via Lua

Overview

Accessing

Properties are functions

Enumeration are strings

Determining object types

Adding an Object With Properties

Working with Collections

Special Collection Objects

Examples

Formatting Rule Post Processing Example to iterate through the frames in a rule:

Creating a dialog box:

Creating a table and inserting text:

Populating Tables with Tabular Fields

Accessing EasyCatalog Scripting Functions

Debugging

What’s New In 2024

EasyCatalog Training

Whats new in 2023

Whats new in 2022

Start your free trial today