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:06] JMichaelTX [How to Install] |
||
---|---|---|---|
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: | ||
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. | ||