Tables are the heart of Numbers, and their creation is a common task that scripts perform. All it takes is a basic understanding of the relationship between tables and sheets.

Tables and Sheets

Tables are elements of sheets. When creating a table, the script must address the sheet on which the table is to be created. Sheets can be addressed using any of these methods:

• By sheet name, such as sheet "2014 Expenses"
• By sheet index number, such as sheet 5
• By using the document property active sheet to target the currently displayed sheet
• By sheet object reference, possibly stored in a variable

Examples of addressing sheets is shown in the script below:

Addressing a Table’s Parent Sheet
01		tell application "Numbers"
02		activate
03
04		if not (exists document 1) then error number -128
05
06		tell document 1
07		-- addressing a sheet by its name
08		tell sheet "2014 Expenses"
09		-- table making command goes here
10		end tell
11
12		-- addressing a sheet by its index value
13		tell sheet 5
14		-- table making command goes here
15		end tell
16
17		-- addressing the currently displayed sheet
18		tell active sheet
19		-- table making command goes here
20		end tell
21
22		-- addressing a stored reference to a specific sheet
23		set thisSheet to make new sheet
24		tell thisSheet
25		-- table making command goes here
26		end tell
27		end tell
28		end tell

Many of the script examples in this section use the document property active sheet as the means of targeting the sheet the user is currently viewing.

Tables are created using the make verb from the Standard Suite of the Numbers scripting dictionary.

Since tables are an element of a sheet, which in turn is an element of a document, the table creation statement containing the make verb (08) must reflect this hierarchy, by occurring within nested tell blocks addressing the parent sheet (07-09) and its parent document (06-10).

Note the use of the document property active sheet (07), the value of which, is the sheet whose content is currently being displayed in the document. This generic property allows scripts to work correctly, regardless of which sheet is currently displayed in the document window.

When the make verb is used (08), it will return a reference, to the newly created table, which can be stored in a variable (thisTable) for later use in the script.

Make New Table on Active Sheet
Open in AppleScript Editor
01		tell application "Numbers"
02		activate
03
04		if not (exists document 1) then error number -128
05
06		tell the front document
07		tell active sheet
08		set thisTable to make new table
09		end tell
10		end tell
11		end tell

To define the number of initial rows and columns for the created table, use the optional with properties parameter of the make verb. Simply follow the parameter with an AppleScript record containing colon-delimited pairings of the property names and their initial values (see 13).

In the script example below, the property values are stored within variables included in the parameter’s record. This optional technique is useful for passing values that are generated dynamically.

NOTE: the character ¬ (placed at the ends of lines 11 & 12) is used to indicate that lines 11-13 are part of a single script statement, which has been segmented and placed on separate lines, for the purpose of fitting within the width constrictions of this column.

Make New Table with N-Rows & N-Columns on Active Sheet
Open in AppleScript Editor
01		set the columnCount to 4
02		set the rowCount to 6
03
04		tell application "Numbers"
05		activate
06
07		if not (exists document 1) then error number -128
08
09		tell the front document
10		tell active sheet
11		set thisTable to ¬
12		make new table with properties ¬
13		{column count:columnCount, row count:rowCount}
14		end tell
15		end tell
16		end tell

The name property of a table can be used to get or set the name assigned to the table. The value of this property can be set during table creation, by including the property and its value in the AppleScript record provided as the value for the with properties parameter of the make verb (see line 15 below).

Make New Named Table on Blank Active Sheet
Open in AppleScript Editor
01		set the columnCount to 4
02		set the rowCount to 6
03		set the tableName to "Project Costs"
04
05		tell application "Numbers"
06		activate
07
08		if not (exists document 1) then error number -128
09
10		tell document 1
11		set thisSheet to make new sheet
12		tell thisSheet
13		delete every table
14		set thisTable to make new table with properties ¬
15		{column count:columnCount, row count:rowCount, name:tableName}
16		end tell
17		end tell
18		end tell

Table Names and Parent Sheets

It is important to note that the value of the name property of a table, must be unique to its parent sheet. Each table on a sheet must have a name different than the other tables on the sheet. Documents can have multiple tables named the same name, but sheets cannot.

NOTE: creating a table on a sheet that contains a table with the same name, will cause a script error. Use the sub-routine provided in the script below, to avoid a name conflict.

From a script perspective, the required uniqueness of a table name only becomes an issue, if you are writing a script that adds a table to an existing sheet. In such cases, it is good scripting practice to have the script check for the names of any existing tables on the target sheet, and to alter the desired name if necessary.

The sub-routine incrementTableNameIfNeeded (lines 19-39 below), can be used to avoid table name conflicts by adding a numeric suffix, if needed, to the desired table name.

Make New Named Table on Active Sheet
Open in AppleScript Editor
01		set the columnCount to 4
02		set the rowCount to 6
03		set the tableName to "Project Costs"
04
05		tell application "Numbers"
06		activate
07
08		if not (exists document 1) then error number -128
09
10		tell the front document
11		tell active sheet
12		set tableName to my incrementTableNameIfNeeded(tableName, "-")
13		set thisTable to make new table with properties ¬
14		{column count:columnCount, row count:rowCount, name:tableName}
15		end tell
16		end tell
17		end tell
18
19		on incrementTableNameIfNeeded(thisTableName, thisDivider)
20		-- a routine for deriving a unique table name based on a provided table name
21		tell application "Numbers"
22		tell the front document
23		tell active sheet
24		-- get a list of the names of the tables on the active sheet
25		set the theseTableNames to the name of every table
26		set the testTableName to the thisTableName
27		set incrementor to 0
28		-- increment the passed name, if needed
29		repeat until testTableName is not in theseTableNames
30		set incrementor to incrementor + 1
31		set the testTableName to ¬
32		the thisTableName & thisDivider & (incrementor as string)
33		end repeat
34		-- return the non-conflicting table name
35		return the testTableName
36		end tell
37		end tell
38		end tell
39		end incrementTableNameIfNeeded