“For Each”

Outlines are closely related to JavaScript arrays, and they often have a one-to-one correspondence. For example, a simple shopping list outline is nothing more than an array of items expressed vertically in sequence. And so it stands to reason that JavaScript functions designed to iterate arrays would be useful in constructing OmniOutliner outline documents.

The forEach() method calls a provided function once for each element in an array, in order. This method is perfectly designed for constructing outlines. Note: forEach() does not execute the function for array elements without values.

For example, in the following script, the forEach() method is applied to the array of children of the rootItem. Note that the method’s processing function is passed each of the children, one-at-a-time, represented by the pass-through variable titled: “child”

The function code can then be applied to the passed “child” object.

Let’s use the forEach() method to clear the current contents of our outline document.

The script will iterate the list of the top-level outline items and delete each instance by applying the remove() method to it. The result will be a blank outline document.

Array to Outline

Now that the document has been cleared, let’s use the forEach() method to construct a simple single-level outline by iterating an array of planet names and creating a new outline entry for each one.

In the following example, note how the content of the created items is set by appending the topic property to the method, and then assigning it a value. This single-line technique (line 3) is perfect for those situations where you don’t need to store a reference to the newly created item.

The result of the script will be a simple outline of top-level items:

As you can see, it’s easy to create a simple outline from a single array of data. Next, we’ll use the forEach() method to create a more complex outline, one with multiple levels of entries.

Before creating the new outline, clear the existing entries.

The outline is now cleared. For the next example, we’ll use data from two arrays to create a multi-level outline.

The “item index” Parameter

The forEach() method takes a processing function as its sole parameter. By default, the function must include a pass-through variable that will contain a reference to the array item being processed. However, there are two other optional parameters for the function that can be represented with variables:

• item index • the position index of the array item currently being processed, beginning with zero (0) for the first item
• the array • a copy of the array being processed by the forEach() method.

Using the optional item index pass-through, we can combine data from two aligned arrays to create an outline. Arrays are said to be “aligned” when they are of the same length and their data is related and in the same order. The following example uses two arrays, a list of the planets, and a list of their moons. Both arrays are of the same length, with related content in the same order.

The result of the script will be the multi-level outline shown below. (I’ve expanded two of the top-level items to reveal their children.)

Object Data to Outline

In the previous example a multi-level outline was created using two data sources (arrays). In the following example, we’ll examine how to create a multi-level outline from a single data source that is a complex JavaScript object.

First, clear the outline of its existing content.

Using JSON (JavaScript Object Notation), data can be stored in either arrays or objects. A JavaScript object is a record of information, represented using an identifying key with a corresponding a data value.

JavaScript objects are placed within curly brackets, with their key and value delimited by a colon ({key:value}). You’ll find that key/value pairing is often used when dealing with stored data.

The following script example demonstrates how to extract the data from a complex JavaScript object and use it to create a multi-level outline in OmniOutliner. In this example, each key is unique — not matching any other key in the parent object. However, it is also common to use the same key for multiple objects, as we’ll examine in another example later in this section.

The result of the script will be the multi-level outline shown below. (I’ve expanded two of the top-level items to reveal their children.)

Array of Keyed Objects

There’s another type of data structure that’s commonly used with JavaScript, and that is an Array of Keyed Objects.

But before examining the new data structure, let’s clear the content from the outline document.

In the following example, the parent container in an array that contains multiple objects that implement the key/value design. In this example, each object utilizes the same two keys: “planet” and “moons”. The corresponding value for the “planet” key is the name of the planet, and the corresponding value for the “moons” key is an array of the names of the larger moons of the planet.

The result of the script will be the multi-level outline shown below. (I’ve expanded two of the top-level items to reveal their children.)

The three shown data-parsing techniques (aligned arrays, data object, and object array) produce the same result of a multi-level outline, regardless of the technique used to store the data.

Summary

In this section you’ve learned how to create and remove items from an outline using the rootItem object and the addChild() and forEach() methods. In creating outlines you’ve parsed JavaScript arrays and objects with key/value pairs. Many of the scripts you write for yourself will incorporate the techniques demonstrated in this section.

What’s Next?

In the next section, we’ll examine how to use the Editor class to manipulate the items in an outline document.