Making Tables

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:

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.

Making a Default Table

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

make  : Create a new object.


new class : The class of the new object.

[ at location specifier ] : The location at which to insert the object.

[ with data any ] : The initial contents of the object.

[ with properties record ] : The initial values for properties of the object.

⇒ specifier : The new object.

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.

Indicating Initial Row and Column Counts

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.

The Table Name Property

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).

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.