Solitary Actions (Simple PlugIn)

In addition to creating and running actions as components in a Plug-In, actions can be written and delivered as stand-alone plug-in files that post a single entry in the Automation menu.

Unlike plugin actions, solitary actions include their identifying metadata in action file as commented object entries at the top of the action script. Note the value of the targets property (line 3) is an array containing the application name or names, targeted by the action.

New File Extension Support

The file extensions used for Omni Automation plug-ins now include app-specific extensions for single-file plug-ins, matching those currently used for plug-in bundles. These changes will be reflected in each of the Omni applications as they are updated over the following months. (posted 7/2020)

The five supported file extensions are:

With the new app-specific file extension support, the plug-in installation process is simplified:

Installing Plug-Ins

Once the action has been written, save it with the file extension of “omnijs” (see file extension information above) and place it within the target application’s Plug-Ins folder, accessed by choosing “Plug-Ins…” from the Automation menu. See the section on Plug-In Installation for detailed instructions.

Solitary Plug-In Metadata

NOTE: the following are the available metadata keys for the action header:

Here is the template for a solitary action (Simple PlugIn):

/*{ "type": "action", "targets": ["omnigraffle","omnioutliner","omniplan","omnifocus"], "author": "Your Name or Company", "identifier": "com.youOrCompany.appInitials.actionName", "version": "1.0", "description": "Description of this action.", "label": "The menu item text", "shortLabel": "Palette Text" }*/ (() => { var action = new PlugIn.Action(function(selection, sender){ // action code }); action.validate = function(selection, sender){ // validation code return true }; return action; })();

Here’s the solitary action template for an OmniOutliner action:

/*{ "type": "action", "targets": ["omnioutliner"], "author": "Your Name or Company", "identifier": "com.youOrCompany.OO.actionName", "version": "1.0", "description": "Description of script.", "label": "Script Name for Automation Menu", "shortLabel": "Script Name for Toolbar Buttons" }*/ (() => { var action = new PlugIn.Action(function(selection, sender) { // action code // selection options: columns, document, editor, items, nodes, styles // action code goes here }); action.validate = function(selection, sender) { // validation code // selection options: columns, document, editor, items, nodes, styles // validation code goes here }; return action; })();

For example, here’s a solitary action template for processing the selected items in an OmniOutliner document:

/*{ "type": "action", "targets": ["omnioutliner"], "author": "Your Name or Company", "identifier": "com.youOrCompany.OO.actionName", "version": "1.0", "description": "A script for processing selected outline items.", "label": "Process Selected Items", "shortLabel": "Selected Rows" }*/ (() => { var action = new PlugIn.Action(function(selection, sender) { // action code // selection options: columns, document, editor, items, nodes, styles selection.items.forEach(function(item){ // processing statements go here }) }); action.validate = function(selection, sender) { // validation code // selection options: columns, document, editor, items, nodes, styles return (selection.items.length > 0) }; return action; })();
xcode://%2F*%7B%0A%09%22type%22%3A%20%22action%22%2C%0A%09%22targets%22%3A%20%5B%22omnioutliner%22%5D%2C%0A%09%22author%22%3A%20%22Your%20Name%20or%20Company%22%2C%0A%09%22description%22%3A%20%22A%20script%20for%20processing%20selected%20outline%20items%2E%22%2C%0A%09%22label%22%3A%20%22Process%20Selected%20Items%22%2C%0A%09%22shortLabel%22%3A%20%22Selected%20Rows%22%0A%7D*%2F%0A%0Avar%20_%20%3D%20function%28%29%7B%0A%09%0A%09var%20action%20%3D%20new%20PlugIn%2EAction%28function%28selection%2C%20sender%29%20%7B%0A%09%09%2F%2F%20action%20code%0A%09%09%2F%2F%20selection%20options%3A%20columns%2C%20document%2C%20editor%2C%20items%2C%20nodes%2C%20styles%0A%09%09selection%2Eitems%2EforEach%28function%28item%29%7B%0A%09%09%09%2F%2F%20processing%20statements%20go%20here%0A%09%09%7D%29%0A%09%7D%29%3B%0A%0A%09action%2Evalidate%20%3D%20function%28selection%2C%20sender%29%20%7B%0A%09%09%2F%2F%20validation%20code%0A%09%09%2F%2F%20selection%20options%3A%20columns%2C%20document%2C%20editor%2C%20items%2C%20nodes%2C%20styles%0A%09%09if%28selection%2Eitems%2Elength%20%3E%200%29%7Breturn%20true%7D%20else%20%7Breturn%20false%7D%0A%09%7D%3B%0A%09%0A%09return%20action%3B%0A%7D%28%29%3B%0A_%3B

Here’s the solitary action template for an OmniGraffle action:

/*{ "type": "action", "targets": ["omnigraffle"], "author": "Your Name or Company", "identifier": "com.youOrCompany.actionName", "version": "1.0", "description": "Description of script.", "label": "Script Name for Automation Menu", "shortLabel": "Script Name for Toolbar Buttons" }*/ (() => { var action = new PlugIn.Action(function(selection, sender) { // action code // selection options: canvas, graphics, lines, solids // action code goes here }); action.validate = function(selection, sender) { // validation code // selection options: canvas, graphics, lines, solids // validation code goes here }; return action; })();

For example, an action for processing selected solids in OmniGraffle:

/*{ "type": "action", "targets": ["omnigraffle"], "author": "Your Name or Company", "identifier": "com.youOrCompany.actionName", "version": "1.0", "description": "A script that processes selected solids.", "label": "Process Selected Solids", "shortLabel": "Process Solids" }*/ (() => { var action = new PlugIn.Action(function(selection, sender){ // action code // selection options: canvas, graphics, lines, solids selection.solids.forEach(function(solid){ // processing statements go here }) }); action.validate = function(selection, sender){ // validation code // selection options: canvas, graphics, lines, solids return (selection.solids.length > 0) }; return action; })();

Action Template Generators

To make creating a solitary action a simpler process, we’ve provided an interactive web interface for generating the solitary action template to fit a variety of scenarios.

Just fill in the metadata and choose the type of input for the action and the webpage will generate the action template, ready for your custom Omni Automation code.

Installing Actions and Plug-ins

Detailed instructions regarding the installation of plug-ins can be found here.

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