Differences

This shows you the differences between two versions of the page.

--- manual:Plug_In_Actions [2021/05/31 20:05]
JMichaelTX ADD section headers
+++ manual:Plug_In_Actions [2021/05/31 21:30]
JMichaelTX ADD Section on how to use; Rewrite how to get parameters
@@ Line 17: / Line 17: @@
   - **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
-    - Then Drop onto the Dock Icon
+    - Then Drop the `.zip` file onto the Dock Icon
+===== How To Use a PIA =====
+_Plug In Actions_ are used just like the built-in Keyboard Maestro [[:Actions|Actions]].
+After you have installed a PIA, you may need to restart both the Keyboard Maestro Editor and Engine in order for the new PIA to be recognized by Keyboard Maestro.
+  - In the Keyboard Maestro Editor, goto _File > Quit Engine_.
+  - Quit and re-launch the Keyboard Maestro Editor.  This will also start the _Engine_.
+To insert a PIA into your Macro, use any of the normal methods to insert Actions:
+  - Display the _Actions Panel_ from the menu or with the shortcut ⌘K, and select the _Third Party Plugins_ folder:
+    * {{ :manual:plugin-folder-in-action-panel.png?nolink |}}
+  - Menu _Edit > Actions > Third Party Plugins_
+  - _Insert Action by Name_, using shortcut ⌘⌃A.
+Configure the PIA as required.
 ===== Building a PIA =====
+==== How to Create a PIA ====
+There is no easy way to create a _Plug In Action_.  There is no one editor (except maybe BBEdit) that can be used to create all of the files that are needed.  Probably the best way to get started is to examine an existing PIA, like this one:
+  * [Fixed Wait for Safari to Finish Loading Plug In Action ](https://forum.keyboardmaestro.com/t/fixed-wait-for-safari-to-finish-loading-plug-in-action/13343) by @PeterNLewis.
+**Steps to Create a PIA**
+  - Create a folder on your local drive, using the same name that you will use for the PIA, put the following files in this folder.
+  - Create a file named FILE{{{Keyboard Maestro Action.plist}}}, which is a standard [Cocoa Property list](https://developer.apple.com/library/archive/documentation/General/Conceptual/DevPedia-CocoaCore/PropertyList.html) file that defines the PIA form.
+    * See [[#PIA_Plist|PIA Plist Definition]] below.
+  - Create a script file named FILE{{{Action.scpt}}}, which can be an AppleScript, JXA, or Shell Script, to process the data from the PIA form.
+  - Create FILE{{{icon.png}}} which is the icon that will be displayed in the Keyboard Maestro Editor.  This file is optional.
+  - When you are finished with all of these files, create a `.zip` archive from the PIA Folder.
 ==== PIA Folder ====
@@ Line 43: / Line 72: @@
 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 ====
@@ Line 59: / Line 88: @@
 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.
 ==== 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.\\
+Note that `spaces` in the variable names _must_ be replaced with `underscores` in your script.
+**Methods To Retrieve Parameters**
 <code applescript>
+--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--»	1.  Use AppleScript "system attribute"
+--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-- This method is "not safe for international characters" (and emoji)
+set myText to system attribute "KMPARAM_My_Text"
+--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--»	2.  Use Shell Script with "echo"
+--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-- This method works with emoji and international characters
+-- but multi-line text (as from a TokenText form field)
+-- will be flattened into a single line
 set myText to do shell script "echo $KMPARAM_My_Text"
+--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--»	3.  Use Shell Script with "printenv"
+--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-- This works with emoji, international characters and multi-line text
+-- however printenv returns an error if KMPARAM_My_Text doesn't exist.
+-- You can catch this error with a try command.
+try
+  set myText to do shell script "printenv KMPARAM_My_Text"
+on error -- Parameter does NOT exit
+  set myText to ""
+end try
 </code>
+==== Reload to Use Updated PIAs ====
 In normal use, once a plug in action is read, it will stay in memory and changes will not be noticed (although the script will be executed each time, so changes to that will be noticed).  To cause the editor and/or engine to notice changes to the plug while in development, use AppleScript to reload the macros:

Keyboard Maestro Wiki

User Tools

Site Tools

Differences

Page Tools