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 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:05] JMichaelTX ADD section headers |
||
|---|---|---|---|
| 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 20: | Line 20: | ||
| ===== 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: | ||
| Line 50: | Line 53: | ||
| | 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 | | | 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 | | | 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: | ||
| Line 59: | Line 65: | ||
| 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 82: | ||
| </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
