Document Selection
In many Omni Automation scripts, it is common practice for the script to process the items or objects the user has selected. Therefore, it is crucial that a script be able to identify the user selection. Here are techniques for determining either the selected nodes (editors) or the selected items (outline) in an OmniOutliner document.
Selected Nodes
To an editor, an item (row) is represented by a node. The selectedNodes property of the Editor class is provided as a way of getting an array (list) of the items (rows) currently selected in the document.
| Selected Nodes | ||
| 01 | document.editors[0].selectedNodes | |
Selection Property (Selection Class)
The Editor class also has a selection property that can be used tp access a variety of selected objects including rows and columns. Its value is an instance of the Selection class.
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 using the object property of the TreeNode.
Using the map() method is an efficient means for deriving an array of selected item objects from an array of selected nodes:
| Get Selected Items | ||
| 01 | sel = document.editors[0].selectedNodes.map(node => {return node.object}) | |
The Selection Parameter (actions)
Omni Automation actions, both solitary and those contained in plug-in bundles, provide an instance of the Selection class to the action and validation handlers in scripts. Each instance of the selection class includes values for each of the following instance properties:
columns (Array of columns r/o) An array of references to the selected columns
document (OutlineDocument or nil r/o) A reference to the parent outline document
editor (Editor or nil r/o) The Editor that contains the selection, or null.
items (Array of Item r/o) An array of references to the selected items (rows)
nodes (Array of ItemTreeNode r/o) The ItemTreeNode instances for the selected rows.
outline (Outline or nil r/o) The Outline that contains the selection, or null.
styles (Array of Styles r/o) An array of the styles used by the selected objects.
Use of these Selection properties enables your scripts to target specific elements of the selection, such as selected rows, or selected columns as shown in the following example of a solitary action:
| Action Template: Selected Columns | ||
| 01 | /*{ | |
| 02 | "type": "action", | |
| 03 | "targets": ["omnioutliner"], | |
| 04 | "author": "Your Name or Company", | |
| 05 | "identifier": "com.youOrCompany.oo.actionName", | |
| 06 | "description": "Logs the titles of the selected columns.", | |
| 07 | "version": "1.0", | |
| 08 | "label": "Titles of Selected Columns", | |
| 09 | "shortLabel": "Selected Columns" | |
| 10 | }*/ | |
| 11 | ||
| 12 | (() => { | |
| 13 | ||
| 14 | var action = new PlugIn.Action(function(selection, sender){ | |
| 15 | // selection options: columns, document, items, outline, or styles | |
| 16 | selection.columns.forEach(function(column){ | |
| 17 | if(column === selection.outline.noteColumn){ | |
| 18 | console.log('Notes: ' + column.title) | |
| 19 | } else if(column === selection.outline.outlineColumn){ | |
| 20 | console.log('Topics: ' + column.title) | |
| 21 | } else { | |
| 22 | console.log(column.title) | |
| 23 | } | |
| 24 | }) | |
| 25 | }); | |
| 26 | ||
| 27 | action.validate = function(selection, sender){ | |
| 28 | // selection options: columns, document, items, outline, or styles | |
| 29 | return (selection.columns.length > 0) | |
| 30 | }; | |
| 31 | ||
| 32 | return action; | |
| 33 | })(); | |
To process the selected items (rows) in an OmniOutliner document, uses the items property of the Selection class to get an array of selected items from the passed instance of the Selection class:
| Action Template: Selected Items (rows) | ||
| 01 | /*{ | |
| 02 | "type": "action", | |
| 03 | "targets": ["omnioutliner"], | |
| 04 | "author": "Your Name or Company", | |
| 05 | "identifier": "com.youOrCompany.oo.actionName", | |
| 06 | "description": "Logs the text of the selected items (rows).", | |
| 07 | "version": "1.0", | |
| 08 | "label": "Topics of Selected Items", | |
| 09 | "shortLabel": "Selected Topics" | |
| 10 | }*/ | |
| 11 | ||
| 12 | (() => { | |
| 13 | ||
| 14 | var action = new PlugIn.Action(function(selection, sender){ | |
| 15 | // selection options: columns, document, items, outline, or styles | |
| 16 | selection.items.forEach(function(item){ | |
| 17 | console.log(item.topic) | |
| 18 | }) | |
| 19 | }); | |
| 20 | ||
| 21 | action.validate = function(selection, sender){ | |
| 22 | // selection options: columns, document, items, outline, or styles | |
| 23 | return (selection.items.length > 0) | |
| 24 | }; | |
| 25 | ||
| 26 | return action; | |
| 27 | })(); | |
The OmniOutliner Template Generator
To make it easier to create your own custom OmniOutliner actions, we suggest using the OmniOutliner Action Template Generator
This webpage is in the process of being developed. Any content may change and may not be accurate or complete at this time.
DISCLAIMER