Omni Automation Actions: Solitary Action

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:

omnijs - Used for plug-ins that target more than one of the Omni applications.
omnifocusjs - Used for plug-ins (both single-file and bundles) that are to be hosted by the OmniFocus application.
omniplanjs - Used for plug-ins (both single-file and bundles) that are to be hosted by the OmniPlan application.
omnigrafflejs - Used for plug-ins (both single-file and bundles) that are to be hosted by the OmniGraffle application.
omnioutlinerjs - Used for plug-ins (both single-file and bundles) that are to be hosted by the OmniOutliner application.

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

Download the plug-in
Open the plug-in file
There is no Step 3! The standard Omni security process will be invoked for the new plug-in.

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:

targets • an array of the lowercase names of the Omni applications targeted by the action.
type • the type is always “action”
identifier • a unique ID used to identify the action. The ID must not contain spaces, and is usually in standard Apple developer format: com.youOrCompany.actionName
version • a numeric string indicating the version of the action, like; 1.2
label • the text shown as an Automation menu item
shortLabel (opt) • the shortest version of the menu title. Also used for icons in the Toolbar picker window.
mediumLabel (opt) • a medium-length version of the menu title
longLabel (opt) • the longest-length version of the menu title

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; })();

Solitary Action Template

/*{

"type": "action",

"targets": ["omnioutliner", "omnigraffle","omniplan","omnifocus"],

"author": "Your Name or Company",

"identifier": "com.youOrCompany.appInitials.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

});

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; })();

OmniOutliner Action Template

/*{

"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

OmniOutliner Action: Process Selected Items

/*{

"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;

})();

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; })();

OmniGraffle Action Template

/*{

"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; })();

OmniGraffle Action: Process Selected Solids

/*{

"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

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.