Finding Outline Items

It is common for scripts to perform their automation tasks by first locating a set of objects that meet a specified set of criteria, and then process the found items. This page contains examples and techniques of how to locate items in an outline document.

The apply(…) instance method of the Item class is very useful for locating items whose properties match specified criteria. The following example functions use this method to locate specific items.

The Item.ApplyResult Class

By default, the apply() method when used with the rootItem object, will iterate every item of the outline, processing each item with the processing code you provide. Optionally, you can use the properties of the Item.ApplyResult class to indicate if an iterated item should be ignored, or if the iteration process should stop.

• Skip (Item.ApplyResult r/o) • The descendants of the current Item are skipped.

• Stop (Item.ApplyResult r/o) • The call to Item.apply terminates with no further items being processed.

• all (Array r/o) • An array of all items of this enumeration. This property is often used when creating action forms.

Using the apply() function to process every item in the outline document:

Using the apply() function to locate and process a specific item:

Using the apply() function to process all items except those whose top-level ancestor matches specific requirements:

Finding by Identifier

For example, here is a function that returns an object reference to the outline item whose identifier matches the one passed into the function. The result will be null if no matching item is located.

NOTE: although the previous example is a valid use of the apply() method, for this example, locating an item by ID is better accomplished using the the itemWithIdentifier() method of the Outline class:

The following function uses the itemWithIdentifier() method of the Outline class to select the item whose ID matches the provided ID string. Note that the reveal(…) function is called before using the select(…) function to ensure that the targeted item is visible before selecting it.

Finding Items by Topic Contents

Locating items based upon their topics (text contents) is a common technique.

Here’s a function, incorporating the apply() method, that returns an object reference to the first item whose text matches the provided string:

A version of the function that returns an array of object references to all items whose topic matches the provided string:

Another search example that returns an object reference to the first item whose text begins with the indicated text:

A function for returning an array of object references to every item whose topic begins with the provided string:

Another search example that returns an object reference to the first item whose text ends with the indicated text:

A function for returning an array of object references to every item whose topic ends with the provided string:

A search example that returns an object reference to the first item whose text includes the indicated text. Notes the includes() method is case sensitive.

A function for returning an array of object references to every item whose topic includes the provided string:

Finding Items by State

Another common search is based upon the state of the item, or the status of it’s checkbox column. This is accomplished by scanning the nodes of the Editor’s rootNode object, since the visible state of items may not match the settings shown in the document window.

The result of the following routine is an array of outline items (rows) whose state matches the value provided as input to the handler.

And here is how the previous function could be called:

And here's a variation of the previous function for identifying items by state, that use the JavaScript filter() method:

Finding Items by Column Cell Value

Here’s an example script that will apply a named style to the row whose cell of a specified column has a value meeting certain requirements, in this case whose numeric value is greater than 100. Note that depending on the applied column format the cell’s value may be Text or Decimal:

Finding Items by Notes

Nulla vitae elit libero, a pharetra augue. Vestibulum id ligula porta felis euismod semper. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor. Maecenas sed diam eget risus varius blandit sit amet non magna. Morbi leo risus, porta ac consectetur ac, vestibulum at eros. Aenean lacinia bibendum nulla sed consectetur. Donec ullamcorper nulla non metus auctor fringilla.