User Tools
manual:Plug_In_Actions
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
|
manual:Plug_In_Actions [2021/05/31 19:55] JMichaelTX Major rewrite providing sections and lists |
manual:Plug_In_Actions [2021/05/31 20:16] JMichaelTX [Plist Parameters] Add Table Column Titles |
||
|---|---|---|---|
| Line 3: | Line 3: | ||
| You can develop custom [[:Actions|Macro Actions]] using a facility known as _Plug In Actions_ (PIA). After you install a _Plug In Action_ in your local Keyboard Maestro Support folder, you can use them like the built-in Actions. | You can develop custom [[:Actions|Macro Actions]] using a facility known as _Plug In Actions_ (PIA). After you install a _Plug In Action_ in your local Keyboard Maestro Support folder, you can use them like the built-in Actions. | ||
| - | ===== Third Party PIA ===== | + | ===== Third Party PIAs ===== |
| - | You download PIA developed by others from these sources: | + | You can download PIAs developed by others from these sources: |
| - [[https://www.stairways.com/action/linkthru?thirdpartyactions|Stairways Web Site]] | - [[https://www.stairways.com/action/linkthru?thirdpartyactions|Stairways Web Site]] | ||
| - [[https://forum.keyboardmaestro.com/c/plugin|Keyboard Maestro Forum]] | - [[https://forum.keyboardmaestro.com/c/plugin|Keyboard Maestro Forum]] | ||
| Line 17: | Line 17: | ||
| - **To Update** An Existing PIA | - **To Update** An Existing PIA | ||
| - First Manually Delete or Move the PIA Sub-Folder from:\\ FILE{{{~/Library/Application Support/Keyboard Maestro/Keyboard Maestro Actions/}}} folder | - First Manually Delete or Move the PIA Sub-Folder from:\\ FILE{{{~/Library/Application Support/Keyboard Maestro/Keyboard Maestro Actions/}}} folder | ||
| - | - Then Drop onto the Dock Icon | + | - Then Drop the `.zip` file onto the Dock Icon |
| ===== Building a PIA ===== | ===== Building a PIA ===== | ||
| + | ==== PIA Folder ==== | ||
| Line 28: | Line 29: | ||
| - Is stored in the Keyboard Maestro Macros.plist to reference the plugin action. | - Is stored in the Keyboard Maestro Macros.plist to reference the plugin action. | ||
| - | The PIA folder contains a set of files, including: | + | **The PIA folder contains a set of files, including:** |
| - Keyboard Maestro Action.plist – an XML file describing the action. | - Keyboard Maestro Action.plist – an XML file describing the action. | ||
| - A script file | - A script file | ||
| Line 37: | Line 38: | ||
| **The PIA Folder must be stored as a `.zip` archive file for installation.** | **The PIA Folder must be stored as a `.zip` archive file for installation.** | ||
| + | |||
| + | ==== PIA PList ==== | ||
| The format of the Keyboard Maestro Action.plist is a [Cocoa Property list](https://developer.apple.com/library/archive/documentation/General/Conceptual/DevPedia-CocoaCore/PropertyList.html) containing a dictionary with the following keys and values: | The format of the Keyboard Maestro Action.plist is a [Cocoa Property list](https://developer.apple.com/library/archive/documentation/General/Conceptual/DevPedia-CocoaCore/PropertyList.html) containing a dictionary with the following keys and values: | ||
| - | | Name | the name of the action (which appears in the Category/Actions list) | | + | ^ Key ^ Description ^ |
| - | | Script | the name of the script, made up of only ASCII alphanumerics or underscores, plus an ASCII alphanumeric extension | | + | ^ Name | the name of the action (which appears in the Category/Actions list) | |
| - | | Icon [optional] | the name of the icon png file, made up of only ASCII alphanumerics or underscores plus .png | | + | ^ Script | the name of the script, made up of only ASCII alphanumerics or underscores, plus an ASCII alphanumeric extension | |
| - | | Title [optional] | the title displayed on the action, which can include %Param%XYZ% tokens. It should usually not include other tokens. If it is missing, the Name will be used | | + | ^ Icon [optional] | the name of the icon png file, made up of only ASCII alphanumerics or underscores plus .png | |
| - | | Timeout [optional number] | the default timeout in seconds. Set it to 0 if the action needs no timeout. The default is 99 hours | | + | ^ Title [optional] | the title displayed on the action, which can include %Param%XYZ% tokens. It should usually not include other tokens. If it is missing, the Name will be used | |
| - | | Author [optional] | the author of this action | | + | ^ Timeout [optional number] | the default timeout in seconds. Set it to 0 if the action needs no timeout. The default is 99 hours | |
| - | | URL [optional] | a URL for the author or this action | | + | ^ Author [optional] | the author of this action | |
| - | | Help [optional] | a short (Tool Tip) explanation of this action | | + | ^ URL [optional] | a URL for the author or this action | |
| - | | Results [optional] | what to do with the output of the script if any. Possible Values: None, Window, Briefly, Typing, Pasting, Variable, Clipboard – multiple values can be used, seperated by a bar (%%|%%), the first specified value is the default | | + | ^ Help [optional] | a short (Tool Tip) explanation of this action | |
| - | | Parameters [optional] | an array of parameters to the script, each entry is a dictionary as described below | | + | ^ Results [optional] | what to do with the output of the script if any. Possible Values: None, Window, Briefly, Typing, Pasting, Variable, Clipboard – multiple values can be used, seperated by a bar (%%|%%), the first specified value is the default | |
| + | ^ Parameters [optional] | an array of parameters to the script, each entry is a dictionary as described below | | ||
| + | ==== Plist Parameters ==== | ||
| Each parameter in the Parameters array is a dictionary with the following keys: | Each parameter in the Parameters array is a dictionary with the following keys: | ||
| - | | Label | the name of the parameter. The same rules as Keyboard Maestro Variable Names apply. The label is displayed to the user and used to pass the parameter to the script. Obviously, the label must be unique amongst all parameters | | + | ^ Parameter Key ^ Description ^ |
| - | | Type | the type of the parameter. Possible Values: String (single line), TokenString, Calculation, Text (multi-line), TokenText, Checkbox (0 or 1), PopupMenu or Hidden. The Type specifies how the value is displayed to the user and what processing is applied before it is passed to the script. Hidden types are text token processed, but are not displayed in the editor | | + | ^ Label | the name of the parameter. The same rules as Keyboard Maestro Variable Names apply. The label is displayed to the user and used to pass the parameter to the script. Obviously, the label must be unique amongst all parameters | |
| - | | Default [optional] | the default value when the action is created | | + | ^ Type | the type of the parameter. Possible Values: String (single line), TokenString, Calculation, Text (multi-line), TokenText, Checkbox (0 or 1), PopupMenu or Hidden. The Type specifies how the value is displayed to the user and what processing is applied before it is passed to the script. Hidden types are text token processed, but are not displayed in the editor | |
| - | | Menu [required if Type is PopupMenu] | the values of the popup menu, separated by %%|%% | | + | ^ Default [optional] | the default value when the action is created | |
| + | ^ Menu [required if Type is PopupMenu] | the values of the popup menu, separated by %%|%% | | ||
| Warning: Keys are case sensitive. | Warning: Keys are case sensitive. | ||
| + | |||
| + | ==== Retrieving Parameters in a Script ==== | ||
| + | |||
| Parameters are passed to the script via environment variables with names starting with KMPARAM‗ similar to how variables are passed to shell scripts with the Execute Script action. So a parameter named "My Text" would be in an environment variable KMPARAM‗My‗Text. You can access the envirnment variables from AppleScript with CODE{{{system attribute "KMPARAM‗My‗Text"}}}. Note that AppleScript’s CODE{{{system attribute}}} is not safe for international characters, although can use code like: | Parameters are passed to the script via environment variables with names starting with KMPARAM‗ similar to how variables are passed to shell scripts with the Execute Script action. So a parameter named "My Text" would be in an environment variable KMPARAM‗My‗Text. You can access the envirnment variables from AppleScript with CODE{{{system attribute "KMPARAM‗My‗Text"}}}. Note that AppleScript’s CODE{{{system attribute}}} is not safe for international characters, although can use code like: | ||
| Line 73: | Line 83: | ||
| </code> | </code> | ||
| - | Keyboard Maestro Plug In Actions go in the FILE{{{~/Library/Application Support/Keyboard Maestro/Keyboard Maestro Actions}}} folder. | + | ==== PIA Failure ==== |
| If the Plug In script fails, the action will fail (v9.0+), potentially aborting the macro. | If the Plug In script fails, the action will fail (v9.0+), potentially aborting the macro. | ||
manual/Plug_In_Actions.txt · Last modified: 2023/10/06 02:28 by peternlewis
Page Tools
