Plug-Ins: Sender Parameter

The selection and sender parameters of a plug-in’s action handlers provide references to the items selected in the application interface, and a reference to the object that triggers the execution of the plug-in.

The value of the sender parameter can be one of three types:

An instance of the MenuItem class
An instance of the ToolbarItem class
A value of undefined if the plug-in was triggered by another script

Here are the properties of the MenuItem class:

checked (Boolean) • If true, a checkmark is displayed next to the MenuItem’s label.
label (String) • The string displayed to describe the MenuItem’s action.

Here are the properties of the ToolbarItem class:

image (Image or null) • The image displayed in the toolbar item
label (String) • The text displayed with the toolbar icon
toolTip (String or null) • The text that appears when the cursor hovers over the toolbar item

Dynamic Menu/Toolbar Title and Image Example

The following example OmniFocus plug-in demonstrates a use of the sender parameter to change the text of the plug-in’s menu item and toolbar item based upon a property (flagged) of the selected task.

If no single task is selected, the menu appears as “Toggle Task Flag.” If a single task is selected, the menu will appear as either “Set Flag to Off” or “Set Flag to On” based upon the state of the flagged property of the selected task.

Toggle Icons, Labels, and Tooltips

How to dynamically adjust based upon the state of an item’s property.

Toggle Task Flag (OmniFocus)
  

/*{
	"type": "action",
	"targets": ["omnifocus"],
	"author": "Otto Automator",
	"identifier": "com.omni-automation.of.sender-example",
	"version": "1.1",
	"description": "An example plug-in showing how to use the sender parameter.",
	"label": "Toggle Task Flag",
	"shortLabel": "Toggle Flag",
	"paletteLabel": "Toggle Flag",
	"image": "flag.filled.and.flag.crossed"
}*/
(() => {
	const action = new PlugIn.Action(function(selection, sender){
		if(selection.tasks.length === 1){
			task = selection.tasks[0]
			task.flagged = !task.flagged
		}
	});

	action.validate = function(selection, sender){
		// sender can be: MenuItem, ToolbarItem, or undefined (remote script)
		if (selection.tasks.length === 1){
			currentState = (selection.tasks[0].flagged)
			if (sender instanceof MenuItem){
				menuText = (currentState)?'Set Flag to Off':'Set Flag to On'
				symbolName = (currentState)?'flag.slash':'flag'
				sender.label = menuText
				sender.image = Image.symbolNamed(symbolName)
			} else if (sender instanceof ToolbarItem){
				menuText = (currentState)?'Turn Flag Off':'Turn Flag On'
				toolbarTip = (currentState)?'Click to Un-Flag':'Click to Flag'
				symbolName = (currentState)?'flag.slash':'flag'
				sender.label = menuText
				sender.image = Image.symbolNamed(symbolName)
				sender.toolTip = toolbarTip
			}
			return true
		}
		// DEFAULT
		sender.label = 'Toggle Task Flag'
		sender.image = Image.symbolNamed("flag.filled.and.flag.crossed")
		sender.toolTip = 'Toggle Task Flag'
		return false
	};
	
	return action;
})();