OmniOutliner: Editors

Editors

To change how an outline looks or is organized, scripts address an Editor.

An element of the Document class, an instance of the Editor class is the entity that controls the display of the outline and its items. By addressing an editor, a script can select, expand, and collapse rows, as well as control the display of columns.

The current editor object is referenced as editor zero (0), meaning it is the first editor in the array of editors currently in use by open document windows. (see below)

var editor = document.editors[0] var tree = document.outline editor.setVisibilityOfColumn(tree.outlineColumn,true) editor.setVisibilityOfColumn(tree.statusColumn,false) editor.setVisibilityOfColumn(tree.noteColumn,false)

omnioutliner:///omnijs-run?script=editor%20%3D%20document%2Eeditors%5B0%5D%0Atree%20%3D%20document%2Eoutline%0Aeditor%2EsetVisibilityOfColumn%28tree%2EoutlineColumn%2Ctrue%29%0Aeditor%2EsetVisibilityOfColumn%28tree%2EstatusColumn%2Cfalse%29%0Aeditor%2EsetVisibilityOfColumn%28tree%2EnoteColumn%2Cfalse%29

Set Visibility of Columns

var editor = document.editors[0]

var tree = document.outline

editor.setVisibilityOfColumn(tree.outlineColumn,true)

editor.setVisibilityOfColumn(tree.statusColumn,false)

editor.setVisibilityOfColumn(tree.noteColumn,false)

Editor Properties

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

focusedItems (Array of Items) • An array of references to the currently focused items.
foldingEnabled (boolean) • When set, cells with text that would layout over multiple lines only show their first line, followed by an ellipsis. Editing a cell that is folded, will temporarily expand it.
noteDisplay (NoteDisplay) • How the notes for each row are displayed, either together with their row when Inline is selected, or in a separate pane with Pane.
rootNode (TreeNode) • Returns a reference to the invisible root node of the Editor.
selectedNodes (Array of TreeNodes r/o) • Returns the list of selected TreeNodes, in the order they appear in the tree. This property is read-only. To select nodes, uses the select method of the Editor instance.
selection (Selection r/o) • Returns the current selection in the editor

Row Text Folding

An example script of setting the property of the current Editor for truncating the text of outline rows:

document.editors[0].foldingEnabled = true

omnioutliner:///omnijs-run?script=document%2Eeditors%5B0%5D%2EfoldingEnabled%20%3D%20true

Row Text Folding

document.editors[0].foldingEnabled = true

Nodes

In terms of an Editor, the individual items of the outline column are called nodes, and references to them are used with commands like the select() command that accepts an array of node references as the objects to select.

var editor = document.editors[0] var node = editor.rootNode.children[0] editor.select([node])

omnioutliner:///omnijs-run?script=editor%20%3D%20document%2Eeditors%5B0%5D%0Anode%20%3D%20editor%2ErootNode%2Echildren%5B0%5D%0Aeditor%2Eselect%28%5Bnode%5D%29

Select First Top-Level Item

var editor = document.editors[0]

var node = editor.rootNode.children[0]

editor.select([node])

Here’s how to leave active editing and deselect all rows:

var editor = document.editors[0] editor.select([])

omnioutliner://localhost/omnijs-run?script=try%7Bvar%20editor%20%3D%20document%2Eeditors%5B0%5D%0Aeditor%2Eselect%28%5B%5D%29%7Dcatch%28err%29%7Bconsole%2Elog%28err%29%7D

Deselect the Editor

var editor = document.editors[0]

editor.select([])

In the following example, the top-level items of the outline (children) are examined to determine the state of their corresponding status checkboxes. If selected, the item is expanded to reveal its descendants, otherwise the item is collapsed.

var editor = document.editors[0] editor.rootNode.children.forEach(function(node){ var nodeState = node.valueForColumn(document.outline.statusColumn) if (nodeState === State.Checked){ node.expand() } else { node.collapse() } })

omnioutliner:///omnijs-run?script=editor%20%3D%20document%2Eeditors%5B0%5D%0Aeditor%2ErootNode%2Echildren%2EforEach%28function%28node%29%7B%0A%09nodeState%20%3D%20node%2EvalueForColumn%28document%2Eoutline%2EstatusColumn%29%0A%09if%20%28nodeState%20%3D%3D%3D%20State%2EChecked%29%7B%0A%09%09node%2Eexpand%28%29%0A%09%7D%20else%20%7B%0A%09%09node%2Ecollapse%28%29%0A%09%7D%0A%7D%29

Expand|Collapse Rows based upon Status

var editor = document.editors[0]

editor.rootNode.children.forEach(function(node){

var nodeState = node.valueForColumn(document.outline.statusColumn)

if (nodeState === State.Checked){

node.expand()

} else {

node.collapse()

}

})

A useful feature of OmniOutliner is the ability to focus the outline display to only show specific items, temporarily hiding the other elements of the outline. Omni Automation scripts have the ability to focus and unfocuse the outline display.

As shown in the following example (line 4), a reference to a node’s corresponding item is the value of the node’s object property.

function focusSelectedItems(){ var editor = document.editors[0] var nodes = editor.selectedNodes var items = nodes.map(function(node){return node.object}) editor.focusedItems = items }

omnioutliner:///omnijs-run?script=function%20focusSelectedItems%28%29%7B%0A%09editor%20%3D%20document%2Eeditors%5B0%5D%0A%09nodes%20%3D%20editor%2EselectedNodes%0A%09items%20%3D%20nodes%2Emap%28function%28node%29%7Breturn%20node%2Eobject%7D%29%0A%09editor%2EfocusedItems%20%3D%20items%0A%7D%0AfocusSelectedItems%28%29

Focus Selected Items

function focusSelectedItems(){

var editor = document.editors[0]

var nodes = editor.selectedNodes

var items = nodes.map(function(node){return node.object})

editor.focusedItems = items

}

function unfocus(){ if (document.editors[0].focusedItems != []){ document.editors[0].focusedItems = [] } }

omnioutliner:///omnijs-run?script=function%20unfocus%28%29%7B%0A%09if%20%28document%2Eeditors%5B0%5D%2EfocusedItems%20%21%3D%20%5B%5D%29%7B%0A%09%09document%2Eeditors%5B0%5D%2EfocusedItems%20%3D%20%5B%5D%0A%09%7D%0A%7D%0Aunfocus%28%29

Unfocus

function unfocus(){

if (document.editors[0].focusedItems != []){

document.editors[0].focusedItems = []

}

And here is an example for focusing only the checked items:

var editor = document.editors[0] var itemsToFocus = new Array() rootItem.descendants.forEach(function(item){ if(editor.nodeForItem(item).state === State.Checked){ itemsToFocus.push(item) } }) if(itemsToFocus.length > 0){editor.focusedItems = itemsToFocus}

omnioutliner://localhost/omnijs-run?script=editor%20%3D%20document%2Eeditors%5B0%5D%0AitemsToFocus%20%3D%20new%20Array%28%29%0ArootItem%2Edescendants%2EforEach%28function%28item%29%7B%0A%09if%28editor%2EnodeForItem%28item%29%2Estate%20%3D%3D%3D%20State%2EChecked%29%7B%0A%09%09itemsToFocus%2Epush%28item%29%0A%09%7D%0A%7D%29%0Aif%28itemsToFocus%2Elength%20%3E%200%29%7Beditor%2EfocusedItems%20%3D%20itemsToFocus%7D

Focus Checked Items

var editor = document.editors[0]

var itemsToFocus = new Array()

rootItem.descendants.forEach(function(item){

if(editor.nodeForItem(item).state === State.Checked){

itemsToFocus.push(item)

}

})

if(itemsToFocus.length > 0){editor.focusedItems = itemsToFocus}

Editor Functions

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

visibilityOfColumn(Column) (--> boolean) • Returns true if the specified Column is visible.
setVisibilityOfColumn(Column, boolean) • Sets the visibility of the specified Column within the Editor.
widthForColumn(Column) (--> Number) • Returns the width in points used to display the Column, assuming a zoom factor of 1.0.
setWidthForColumn(Column, Number) • Sets the width in points used to display the Column, assuming a zoom factor of 1.0.
sortOrderingForColumn(Column) (--> SortOrdering or nil) • Returns the current sort ordering in this editor for the specified Column, or null if no ordering is set.
setSortOrderingForColumn(Column, SortOrdering or nil) • Changes the sort ordering for the specified Column in this editor.
withoutSorting(Function) (--> Object or nil) • Temporarily disables any automatic sorting while running the passed in Function (which is invoked with zero arguments). The result of the function is returned.
summaryForColumn(Column) (--> Column.Summary or nil) • Returns the current Summary used to calculate cells value for parent items in the specified Column, or null if the values are directly editable.
setSummaryForColumn(Column, Column.Summary or nil) • Sets or clears the Summary used to calculate cells value for parent items.
beforeColumn(Column or nil) (--> EditorColumnPosition) • Returns an EditorColumnPosition that indicates the slot before the specified column, or before all columns if null is given.
afterColumn(Column or nil) (--> EditorColumnPosition) • Returns an EditorColumnPosition that indicates the slot after the specified column, or after all columns if null is given.
nodeForItem(Item) (--> TreeNode or nil) • Deprecated: Please use nodeForObject() instead. Returns the TreeNode that represents the item in this Editor, or null if it cannot be found (possibly filtered out, or not contained in the focusedItems).
nodesForItems(Items) (--> TreeNodes) • Deprecated: Please use nodeForObjects() instead. Returns an array of TreeNodes for the Items that are currently in the Editor’s filtered and focused view. The size of the resulting node array may be smaller (even empty) than the passed in items array.
nodeForObject(object:Object) (TreeNode or null) • Returns the TreeNode that represents the object in this Tree, or null if it cannot be found (possibly filtered out).
nodesForObjects(object:Array of Object) (Array of TreeNode) • Returns an array of TreeNodes for the objects that are currently in the Tree, according to the same filters as nodeForObject(). The size of the resulting node array may be smaller (even empty) than the passed in objects array.
reveal(TreeNodes) • Ensures the ancestor nodes of all the specified nodes are expanded.
select(TreeNodes, extendingBoolean or nil) • Selects the specified TreeNodes that are visible (nodes with collapsed ancestors cannot be selected). If extending is true, the existing selection is not cleared.
scrollToNode(TreeNode) • Attempts to scroll the view so that the specified TreeNode is visible. If the node is not revealed due to a collapsed ancestor, this may not be possible and no scrolling will be performed.
indentNodes(TreeNodes) • Indents the specified nodes one level, or throws an error if that isn’t possible.
outdentNodes(TreeNodes) • Outdents the specified nodes one level, or throws an error if that isn’t possible.
copyNodes(TreeNodes, Pasteboard) • Copies the listed nodes to the indicated pasteboard.
paste(Pasteboard, TreeNode, childIndex) • Inserts the nodes on the pasteboard into the outline.

Here’s how to convert an item (row) reference into a node reference:

var row = rootItem.children[0] var editor = document.editors[0] var node = editor.nodeForObject(row)

Node for Item

var row = rootItem.children[0]

var editor = document.editors[0]

var node = editor.nodeForObject(row)

Here’s an example script using the scrollToNode() method to scroll the outline document to the top:

var editor = document.editors[0] editor.scrollToNode(editor.rootNode.children[0])

omnioutliner:///omnijs-run?script=editor%20%3D%20document%2Eeditors%5B0%5D%0Aeditor%2EscrollToNode%28editor%2ErootNode%2Echildren%5B0%5D%29

Scroll to the Top

var editor = document.editors[0]

editor.scrollToNode(editor.rootNode.children[0])

Here’s an example script using the outdentNodes() method to move the selected row to the top-level in the outline:

var editor = document.editors[0] var node = editor.selectedNodes[0] while (node.level != 1){ editor.outdentNodes([node]) node = editor.selectedNodes[0] }

omnioutliner:///omnijs-run?script=editor%20%3D%20document%2Eeditors%5B0%5D%0Anode%20%3D%20editor%2EselectedNodes%5B0%5D%0Awhile%20%28node%2Elevel%20%21%3D%201%29%7B%0A%09editor%2EoutdentNodes%28%5Bnode%5D%29%0A%09node%20%3D%20editor%2EselectedNodes%5B0%5D%0A%7D

Move Selected Row to Top Level

var editor = document.editors[0]

var node = editor.selectedNodes[0]

while (node.level != 1){

editor.outdentNodes([node])

node = editor.selectedNodes[0]

}

Here’s a script that uses the visibilityOfColumn() method to derive references to the visible columns:

var editor = document.editors[0] var visibleColumns = columns.map(column => { if (editor.visibilityOfColumn(column)){return column} })

Get the Visible Columns

var editor = document.editors[0]

var visibleColumns = columns.map(column => {

if (editor.visibilityOfColumn(column)){return column}

})

EditorColumnPosition

Instances of the EditorColumnPosition class are generated by using one of the following methods with an instance of the Editor class:

beforeColumn(Column or nil) (--> EditorColumnPosition) • Returns an instance of the EditorColumnPosition class that indicates the slot before the specified column, or before all columns if null is given.
afterColumn(Column or nil) (--> EditorColumnPosition) • Returns an instance of the EditorColumnPosition class that indicates the slot after the specified column, or after all columns if null is given.

columnPosition = document.editors[0].afterColumn(document.outline.outlineColumn)

Editor Column Position

pos = document.editors[0].afterColumn(document.outline.outlineColumn)

The following example script uses the addColumn(…) function of the Column class to append a numeric column to the end of the outline. Also note that since a null value is entered rather than an instance of the EditorColumnPosition class for the parameter of the afterColumn(…) method, the new column is created after the last column.

var tree = document.outline var editor = document.editors[0] var newCol = tree.addColumn( Column.Type.Number, editor.afterColumn(null), null ) newCol.title = 'Q2' editor.setSummaryForColumn(newCol, Column.Summary.Total)

omnioutliner://localhost/omnijs-run?script=try%7Bvar%20tree%20%3D%20document%2Eoutline%0Avar%20editor%20%3D%20document%2Eeditors%5B0%5D%0Avar%20newCol%20%3D%20tree%2EaddColumn%28%0A%09Column%2EType%2ENumber%2C%0A%09editor%2EafterColumn%28null%29%2C%20%0A%09null%0A%29%0AnewCol%2Etitle%20%3D%20%27Q2%27%0Aeditor%2EsetSummaryForColumn%28newCol%2C%20Column%2ESummary%2ETotal%29%7Dcatch%28err%29%7Bconsole%2Elog%28err%29%7D

Add Numeric Column to Outline

var tree = document.outline

var editor = document.editors[0]

var newCol = tree.addColumn(

Column.Type.Number,

editor.afterColumn(null),

null

)

newCol.title = 'Q2'

editor.setSummaryForColumn(newCol, Column.Summary.Total)

SortOrdering Properties

The properties of the SortOrdering class are used as the value for the sorting methods sortOrderingForColumn and setSortOrderingForColumn of the Editor class:

Ascending • Sort smaller numerical or lexigraphically preceding values first.
Descending • Sort larger numerical or lexigraphically later values first.

var editor = document.editors[0] var column = document.outline.outlineColumn var sortStatus = editor.sortOrderingForColumn(column) if (sortStatus != SortOrdering.Descending){ editor.setSortOrderingForColumn(column, SortOrdering.Descending) }

omnioutliner:///omnijs-run?script=editor%20%3D%20document%2Eeditors%5B0%5D%0Acolumn%20%3D%20document%2Eoutline%2EoutlineColumn%0AsortStatus%20%3D%20editor%2EsortOrderingForColumn%28column%29%0Aif%20%28sortStatus%20%21%3D%20SortOrdering%2EDescending%29%7B%0A%09editor%2EsetSortOrderingForColumn%28column%2C%20SortOrdering%2EDescending%29%0A%7D

Sort Outline Column as Descending

var editor = document.editors[0]

var column = document.outline.outlineColumn

var sortStatus = editor.sortOrderingForColumn(column)

if (sortStatus != SortOrdering.Descending){

editor.setSortOrderingForColumn(column, SortOrdering.Descending)

}

NoteDisplay Properties

The properties of the NoteDisplay class are used for the value of the noteDisplay property (note lowercase n) of the Editor class:

Inline • Display notes inline with the row.
Pane • Display notes in a separate pane.

Editors can be used to control the manner in which notes are displayed:

var alert = new Alert("NOTES DISPLAY", "Display item notes inline or at the bottom of the pane?") alert.addOption("Inline") alert.addOption("Pane") alert.show(function(result){ if (result == 0){ document.editors[0].noteDisplay = NoteDisplay.Inline } else { document.editors[0].noteDisplay = NoteDisplay.Pane } })

omnioutliner:///omnijs-run?script=var%20alert%20%3D%20new%20Alert%28%22NOTES%20DISPLAY%22%2C%20%22Display%20item%20notes%20inline%20or%20at%20the%20bottom%20of%20the%20pane%3F%22%29%0Aalert%2EaddOption%28%22Inline%22%29%0Aalert%2EaddOption%28%22Pane%22%29%0Aalert%2Eshow%28function%28result%29%7B%0A%09if%20%28result%20%3D%3D%200%29%7B%0A%09%09document%2Eeditors%5B0%5D%2EnoteDisplay%20%3D%20NoteDisplay%2EInline%0A%09%7D%20else%20%7B%0A%09%09document%2Eeditors%5B0%5D%2EnoteDisplay%20%3D%20NoteDisplay%2EPane%0A%09%7D%0A%7D%29

Set Note Display

var alert = new Alert("NOTES DISPLAY", "Display item notes inline or at the bottom of the pane?")

alert.addOption("Inline")

alert.addOption("Pane")

alert.show(function(result){

if (result == 0){

document.editors[0].noteDisplay = NoteDisplay.Inline

} else {

document.editors[0].noteDisplay = NoteDisplay.Pane

}

})

Value for Column

Here’s a plug-in example that uses the valueForColumn(…) function to display the sum of the numeric columns of the selected row:

/*{ "type": "action", "targets": ["omnioutliner"], "author": "Otto Automator", "identifier": "com.omni-automation.oo.numeric-row-sum", "version": "1.0", "description": "Display the numeric value of the numeric columns of the selected row.", "label": "Sum of Selected Row", "shortLabel": "Row Sum" }*/ (() => { var action = new PlugIn.Action(function(selection, sender){ // action code // selection options: columns, document, editor, items, nodes, outline, styles var item = selection.items[0] var numericColumns = new Array() columns.forEach(col => { if (col.type === Column.Type.Number){numericColumns.push(col)} }) if (numericColumns.length != 0){ var total = Decimal.zero numericColumns.forEach(col => { total = total.add(item.valueForColumn(col)) }) new Alert("SUM: ", total.toString()).show() } else { message = "The selected row contains no numeric columns." new Alert("Missing Columns", message).show() } }); action.validate = function(selection, sender){ // validation code // selection options: columns, document, editor, items, nodes, outline, styles return (selection.items.length === 1) }; return action; })();

Display Sum of Numeric Columns of Selected Row

/*{

"type": "action",

"targets": ["omnioutliner"],

"author": "Otto Automator",

"identifier": "com.omni-automation.oo.numeric-row-sum",

"description": "Display the sum of the numeric values of the numeric columns of the selected row.",

"label": "Sum of Selected Row",

"shortLabel": "Row Sum"

}*/

(() => {

var action = new PlugIn.Action(function(selection, sender){

// action code

// selection options: columns, document, editor, items, nodes, outline, styles

var item = selection.items[0]

var numericColumns = new Array()

columns.forEach(col => {

if (col.type === Column.Type.Number){numericColumns.push(col)}

})

if (numericColumns.length != 0){

var total = Decimal.zero

numericColumns.forEach(col => {

total = total.add(item.valueForColumn(col))

})

new Alert("SUM: ", total.toString()).show()

} else {

message = "The selected row contains no numeric columns."

new Alert("Missing Columns", message).show()

}

});

action.validate = function(selection, sender){

// validation code

// selection options: columns, document, editor, items, nodes, outline, styles

return (selection.items.length === 1)

};

return action;

})();

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

Mention of third-party websites and products is for informational purposes only and constitutes neither an endorsement nor a recommendation. OMNI-AUTOMATION.COM assumes no responsibility with regard to the selection, performance or use of information or products found at third-party websites. OMNI-AUTOMATION.COM provides this only as a convenience to our users. OMNI-AUTOMATION.COM has not tested the information found on these sites and makes no representations regarding its accuracy or reliability. There are risks inherent in the use of any information or products found on the Internet, and OMNI-AUTOMATION.COM assumes no responsibility in this regard. Please understand that a third-party site is independent from OMNI-AUTOMATION.COM and that OMNI-AUTOMATION.COM has no control over the content on that website. Please contact the vendor for additional information.