Items

When working in the outline, the building blocks of your content are referred to as rows.

Rows can appear as simple as a line of text, but many outline styles also display other common components to the row such as handles, notes, and status checkboxes. Rows can also span multiple columns (if your document has more than one).

In scripting terms, rows are items, which are instances of the Item class.

The Root Item

All rows in an outline are children or descendents of an invisible item called the the rootItem. The value of the rootItem property of the outline class, it is the invisible topmost item in the hierarchy of the topic column.

As shown in the illustration of hierarchical examples on this page, the rootItem is always the topmost element in the hierarchy.

Referencing rootItem of a New Document

NOTE: if your script needs to access the rootItem of a document created by the script itself, use the rootNode property of the current instance of the Editor class to derive the rootItem object. To avoid a name space conflict, do not store the referenced rootItem in a variable named “rootItem”, use “baseItem” instead:

Document.makeNewAndShow(function(doc){ baseItem = doc.editors[0].rootNode.object baseItem.addChild(null,function(item){item.topic = 'HELLO WORLD'}) })
omnioutliner://localhost/omnijs-run?script=Document%2EmakeNewAndShow%28function%28doc%29%7B%0A%09baseItem%20%3D%20doc%2Eeditors%5B0%5D%2ErootNode%2Eobject%0A%09baseItem%2EaddChild%28null%2Cfunction%28item%29%7Bitem%2Etopic%20%3D%20%27HELLO%20WORLD%27%7D%29%0A%7D%29

Item Relational Properties

The items (rows) of an outline document have relationships that are defined using terms that are similar to those used to describe a human relationships in an ancestral hierarchy. For example, an item may have children, siblings, descendents, and ancestors. Here are the relational properties of the item class:

The illustrations below represent some of the relational properties of the item class:

Item Properties

rootItem

rootItem.children

rootItem.descendants

rootItem.leaves

root root-children root-descendants root-leaves

item

item.children

item.descendants

item.leaves

root root-children root-descendants root-leaves

item.followingSiblings

item.precedingSiblings

item.parent

item.ancestors

root-children root-descendants root root-leaves

Item Instance Properties

Here are the properties of an instance of the Item class:

Since the value for identifier property is not able to be viewed in the document UI, here’s a script for displaying the ID of a selected outline item. You can copy the ID from the dialog or from the console window. TAP|CLICK to install script as a solitary action.

var nodes = document.editors[0].selectedNodes if (nodes.length != 1){ errTitle = 'SELECTION ERROR' errMesssage = 'Please select a single item.' alert = new Alert(errTitle,errMesssage) alert.show(function(result){throw new Error(errMesssage)}) } else { items = nodes.map(function(node){return node.object}) itemID = items[0].identifier console.log(itemID) new Alert(items[0].topic,itemID).show(function(result){}) }
omnioutliner:///omnijs-run?script=var%20nodes%20%3D%20document%2Eeditors%5B0%5D%2EselectedNodes%0Aif%20%28nodes%2Elength%20%21%3D%201%29%7B%0A%09errTitle%20%3D%20%27SELECTION%20ERROR%27%0A%09errMesssage%20%3D%20%27Please%20select%20a%20single%20item%2E%27%0A%09alert%20%3D%20new%20Alert%28errTitle%2CerrMesssage%29%0A%09alert%2Eshow%28function%28result%29%7Bthrow%20new%20Error%28errMesssage%29%7D%29%0A%7D%20else%20%7B%0A%09items%20%3D%20nodes%2Emap%28function%28node%29%7Breturn%20node%2Eobject%7D%29%0A%09itemID%20%3D%20items%5B0%5D%2Eidentifier%0A%09console%2Elog%28itemID%29%0A%09new%20Alert%28items%5B0%5D%2Etopic%2CitemID%29%2Eshow%28function%28result%29%7B%7D%29%0A%7D

Getting Selected Items

References to selected outline items are acquired through the use of the selectedNodes property of the Editor class. The value of this property is an array of TreeNodes. The item represented by a TreeNode is accessed through the object property of the TreeNode.

Using the map() method is an efficient means for deriving an array of selected item objects:

selectedItems = document.editors[0].selectedNodes.map(function(node){return node.object})
selectedItems = document.editors[0].selectedNodes.map(function(node){return node.object}) if (selectedItems.length == 0){ errTitle = 'SELECTION ERROR' errMesssage = 'No items are selected.' alert = new Alert(errTitle,errMesssage) alert.show(function(result){throw new Error(errMesssage)}) } else { // process items }

The following script creates and displays an Alert dialog showing the text (topic) of the single selected item:

selectedItems = document.editors[0].selectedNodes.map(function(node){return node.object}) if (selectedItems.length != 1){ errTitle = 'SELECTION ERROR' errMesssage = 'Please select a single item.' alert = new Alert(errTitle,errMesssage) alert.show(function(result){throw new Error(errMesssage)}) } else { // process item selectedItem = selectedItems[0] new Alert('Item Text',selectedItem.topic).show(function(result){}) }

The topic property of the item class is provided as a way to make it easier for scripts to retrieve and set the value of the topic column (outlineColumn) of an item. The following script shows how the value of a specified column is retrieved using the valueForColumn() method. Compare it to the version above.

selectedItems = document.editors[0].selectedNodes.map(function(node){return node.object}) if (selectedItems.length != 1){ errTitle = 'SELECTION ERROR' errMesssage = 'Please select a single item.' alert = new Alert(errTitle,errMesssage) alert.show(function(result){throw new Error(errMesssage)}) } else { // process item selectedItem = selectedItems[0] targetColumn = document.outline.outlineColumn itemValue = selectedItem.valueForColumn(targetColumn).string new Alert('Item Text',itemValue).show(function(result){}) }

Getting Outline Contents

The following example script demonstrates how to extract the basic text contents of the outline, inserting tab characters for paragraph indents:

var topics = new Array() var indent = '\t' rootItem.descendants.forEach(function(item){ level = item.level if (level > 1){ itemString = indent.repeat(level-1) + item.topic } else { itemString = item.topic } topics.push(itemString) }) topics.join('\n')
 

Adding Items

Items are added to an outline using the addChild() method:

For example, here’s how to add a top-level item (row) to the outline by calling the addChild() method on the rootItem:

newRow = rootItem.addChild()
omnioutliner://localhost/omnijs-run?script=newRow%20%3D%20rootItem%2EaddChild%28%29

In the following example, a new child item is added the first selected item (row):

// add a child to the end of children of the first selected item // note the use of the “object” property of the TreeNode class document.editors[0].selectedNodes[0].object.addChild()
omnioutliner:///omnijs-run?script=document%2Eeditors%5B0%5D%2EselectedNodes%5B0%5D%2Eobject%2EaddChild%28%29

Item Position Properties

The item position properties are used to identify the position of a child item within its parental hierarchy.

Here are example scripts using the item position properties. In each example, a new item (child) is created using the addChild() instance method, which takes as its parameters, the item position at which the new item is added (line 6), and an optional function for manipulating the created item (line 7).

Note the use of the object property of the Node class (line 4) to retrieve a reference to the node (row) as an instance of the Item class:

// add child after the second child of selected item nodes = document.editors[0].selectedNodes if(nodes.length != 0){ var selectedItem = nodes[0].object selectedItem.addChild( selectedItem.children[1].after, function(item){ item.topic = "NEW THIRD CHILD" } ) }
omnioutliner:///omnijs-run?script=nodes%20%3D%20document%2Eeditors%5B0%5D%2EselectedNodes%0Aif%28nodes%2Elength%20%21%3D%200%29%7B%0A%09var%20selectedItem%20%3D%20nodes%5B0%5D%2Eobject%0A%09selectedItem%2EaddChild%28%0A%09%09selectedItem%2Echildren%5B1%5D%2Eafter%2C%0A%09%09function%28item%29%7B%0A%09%09%09item%2Etopic%20%3D%20%22NEW%20THIRD%20CHILD%22%0A%09%09%7D%0A%09%29%0A%7D
// add child before the second child of selected item nodes = document.editors[0].selectedNodes if(nodes.length != 0){ var selectedItem = nodes[0].object selectedItem.addChild( selectedItem.children[1].before, function(item){ item.topic = "NEW SECOND CHILD" } ) }
omnioutliner:///omnijs-run?script=nodes%20%3D%20document%2Eeditors%5B0%5D%2EselectedNodes%0Aif%28nodes%2Elength%20%21%3D%200%29%7B%0A%09var%20selectedItem%20%3D%20nodes%5B0%5D%2Eobject%0A%09selectedItem%2EaddChild%28%0A%09%09selectedItem%2Echildren%5B1%5D%2Ebefore%2C%0A%09%09function%28item%29%7B%0A%09%09%09item%2Etopic%20%3D%20%22NEW%20SECOND%20CHILD%22%0A%09%09%7D%0A%09%29%0A%7D
// add child at the beginning of children of selected item nodes = document.editors[0].selectedNodes if(nodes.length != 0){ var selectedItem = nodes[0].object selectedItem.addChild( selectedItem.beginning, function(item){ item.topic = "NEW BEGINNING ITEM" } ) }
omnioutliner:///omnijs-run?script=nodes%20%3D%20document%2Eeditors%5B0%5D%2EselectedNodes%0Aif%28nodes%2Elength%20%21%3D%200%29%7B%0A%09var%20selectedItem%20%3D%20nodes%5B0%5D%2Eobject%0A%09selectedItem%2EaddChild%28%0A%09%09selectedItem%2Ebeginning%2C%0A%09%09function%28item%29%7B%0A%09%09%09item%2Etopic%20%3D%20%22NEW%20BEGINNING%20ITEM%22%0A%09%09%7D%0A%09%29%0A%7D
// add child at the end of children of selected item nodes = document.editors[0].selectedNodes if(nodes.length != 0){ var selectedItem = nodes[0].object selectedItem.addChild( selectedItem.end, function(item){ item.topic = "NEW ENDING ITEM" } ) }
omnioutliner:///omnijs-run?script=nodes%20%3D%20document%2Eeditors%5B0%5D%2EselectedNodes%0Aif%28nodes%2Elength%20%21%3D%200%29%7B%0A%09var%20selectedItem%20%3D%20nodes%5B0%5D%2Eobject%0A%09selectedItem%2EaddChild%28%0A%09%09selectedItem%2Eend%2C%0A%09%09function%28item%29%7B%0A%09%09%09item%2Etopic%20%3D%20%22NEW%20ENDING%20ITEM%22%0A%09%09%7D%0A%09%29%0A%7D

When creating an item position for a sibling of an item, reference the parent of the item and use the item’s position to indicate where the new item should be inserted:

// add preceding sibling nodes = document.editors[0].selectedNodes if(nodes.length != 0){ var selectedItem = nodes[0].object var selectedItemParent = selectedItem.parent selectedItemParent.addChild( selectedItem.before, function(item){ item.topic = "NEW PRECEDING SIBLING ITEM" } ) }
omnioutliner:///omnijs-run?script=nodes%20%3D%20document%2Eeditors%5B0%5D%2EselectedNodes%0Aif%28nodes%2Elength%20%21%3D%200%29%7B%0A%09var%20selectedItem%20%3D%20nodes%5B0%5D%2Eobject%0A%09var%20selectedItemParent%20%3D%20selectedItem%2Eparent%0A%09selectedItemParent%2EaddChild%28%0A%09%09selectedItem%2Ebefore%2C%0A%09%09function%28item%29%7B%0A%09%09%09item%2Etopic%20%3D%20%22NEW%20PRECEDING%20SIBLING%20ITEM%22%0A%09%09%7D%0A%09%29%0A%7D
// add following sibling nodes = document.editors[0].selectedNodes if(nodes.length != 0){ var selectedItem = nodes[0].object var selectedItemParent = selectedItem.parent selectedItemParent.addChild( selectedItem.after, function(item){ item.topic = "NEW FOLLOWING SIBLING ITEM" } ) }
omnioutliner:///omnijs-run?script=nodes%20%3D%20document%2Eeditors%5B0%5D%2EselectedNodes%0Aif%28nodes%2Elength%20%21%3D%200%29%7B%0A%09var%20selectedItem%20%3D%20nodes%5B0%5D%2Eobject%0A%09var%20selectedItemParent%20%3D%20selectedItem%2Eparent%0A%09selectedItemParent%2EaddChild%28%0A%09%09selectedItem%2Eafter%2C%0A%09%09function%28item%29%7B%0A%09%09%09item%2Etopic%20%3D%20%22NEW%20FOLLOWING%20SIBLING%20ITEM%22%0A%09%09%7D%0A%09%29%0A%7D

Item Methods (functions)

Here are the methods used with an instance of the Item class:

Here’s short script that uses the valueForColumn() method to copy the contents of a column into the notes field of each top-level row.

rootItem.children.forEach(function(item){ item.note = item.valueForColumn(columns.byTitle('Title of Column to Copy')).string })
 

State Properties

The State properties are the value for the state property of the Item class:

item = document.editors[0].selectedNodes[0].object if(item.state == State.Checked){ message = "Selected item status is checked." } else if (item.state == State.Mixed){ message = "Selected item status is mixed." } else { message = "Selected item status is unchecked." } new Alert('STATUS',message).show(function(result){})
omnioutliner:///omnijs-run?script=item%20%3D%20document%2Eeditors%5B0%5D%2EselectedNodes%5B0%5D%2Eobject%0Aif%28item%2Estate%20%3D%3D%20State%2EChecked%29%7B%0A%09message%20%3D%20%22Selected%20item%20status%20is%20checked%2E%22%0A%7D%20else%20if%20%28item%2Estate%20%3D%3D%20State%2EMixed%29%7B%0A%09message%20%3D%20%22Selected%20item%20status%20is%20mixed%2E%22%0A%7D%20else%20%7B%0A%09message%20%3D%20%22Selected%20item%20status%20is%20unchecked%2E%22%0A%7D%0Anew%20Alert%28%27STATUS%27%2Cmessage%29%2Eshow%28function%28result%29%7B%7D%29
UNDER CONSTRUCTION

This webpage is in the process of being developed. Any content may change and may not be accurate or complete at this time.

DISCLAIMER