User Tools

Site Tools


manual:Plug_In_Actions

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
manual:Plug_In_Actions [2021/06/01 13:13]
JMichaelTX [PIA PList]
manual:Plug_In_Actions [2023/10/06 02:28] (current)
peternlewis [Retrieving Parameters in a Script]
Line 1: Line 1:
 ====== Plug In Actions ====== ====== Plug 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.+You can develop custom [[:​Actions|Macro Actions]] using a facility known as _Plug In Actions_. ​ 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 PIAs =====+===== Third Party Plug In Actions ​=====
  
-You can download ​PIAs developed by others from these sources:+You can download ​Plug In Actions ​developed by others from these sources:
   - [[https://​www.stairways.com/​action/​linkthru?​thirdpartyactions|Keyboard Maestro Web Site]]   - [[https://​www.stairways.com/​action/​linkthru?​thirdpartyactions|Keyboard Maestro Web Site]]
   - [[https://​forum.keyboardmaestro.com/​c/​plugin|Keyboard Maestro Forum]]   - [[https://​forum.keyboardmaestro.com/​c/​plugin|Keyboard Maestro Forum]]
Line 11: Line 11:
 ===== How to Install ===== ===== How to Install =====
  
-PIA Install Files are `.zip` Archive Files+Plug In Action ​Install Files are `.zip` Archive Files
   - **Initial Install:** Drop on the Keyboard Maestro app Dock icon   - **Initial Install:** Drop on the Keyboard Maestro app Dock icon
-    * This will create a PIA sub-folder by the same name as the `.zip` file+    * This will create a Plug In Action ​sub-folder by the same name as the `.zip` file
     * Do _not_ unzip the file     * Do _not_ unzip the file
-  - **To Update** An Existing ​PIA +  - **To Update** An Existing ​Plug In Action 
-    - 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 Plug In Action ​Sub-Folder from:\\ FILE{{{~/​Library/​Application Support/​Keyboard Maestro/​Keyboard Maestro Actions/}}} folder
     - Then Drop the `.zip` file onto the Dock Icon     - Then Drop the `.zip` file onto the Dock Icon
  
-===== How To Use a PIA =====+===== How To Use a Plug In Action ​=====
  
 _Plug In Actions_ are used just like the built-in Keyboard Maestro [[:​Actions|Actions]]. _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.+After you have installed a Plug In Action, you may need to restart both the Keyboard Maestro Editor and Engine in order for the new Plug In Action ​to be recognized by Keyboard Maestro.
   - In the Keyboard Maestro Editor, goto _File > Quit Engine_.   - In the Keyboard Maestro Editor, goto _File > Quit Engine_.
   - Quit and re-launch the Keyboard Maestro Editor. ​ This will also start the _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:+To insert a Plug In Action ​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:   - 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 |}} +    * {{:​manual:​plugin-folder-in-action-panel.png?​nolink|}} ​
   - Menu _Edit > Actions > Third Party Plugins_   - Menu _Edit > Actions > Third Party Plugins_
   - _Insert Action by Name_, using shortcut ⌘⌃A.   - _Insert Action by Name_, using shortcut ⌘⌃A.
-Enter the PIA form fields (parameters) that are shown on the action form.+Enter the Plug In Action ​form fields (parameters) that are shown on the action form.
  
-===== Building a PIA =====+===== Building a Plug In Action ​=====
  
-==== How to Create a PIA ====+==== How to Create a Plug In Action ​====
  
-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:+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 ​Plug In Action, 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.   * [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** +**Steps to Create a Plug In Action** 
-  - 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. +  - **Folder:​**  ​Create a folder on your local drive, using the same name that you will use for the Plug In Action, 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. +  - **Plist:​**  ​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 Plug In Action ​form. 
-    * See [[Plug_In_Actions#​PIA_PList|PIA Plist Definition]] below. +    * See [[Plug_In_Actions#​Plug_In_Action_PList|Plug In Action ​Plist Definition]] below. 
-    * The PIA Plist is an XML which defines the Action form you see in the Keyboard Maestro Editor, and identifies the name of the script file that will be run when the PIA is executed in a triggered macro. +    * The Plug In Action ​Plist is an XML which defines the Action form you see in the Keyboard Maestro Editor, and identifies the name of the script file that will be run when the Plug In Action ​is executed in a triggered macro. 
-  - Create a script file named FILE{{{Action.scpt}}},​ or other suitable name (like the name of your PIA), which can be an AppleScript,​ JXA, or Shell Script, to process the data from the PIA form. +  - **Script:​**  ​Create a script file named FILE{{{Action.scpt}}},​ or other suitable name (like the name of your Plug In Action), which can be an AppleScript,​ JXA, or Shell Script, to process the data from the Plug In Action ​form. 
-  - Create FILE{{{icon.png}}} which is the icon that will be displayed in the Keyboard Maestro Editor. ​ This file is optional. +  - **Icon:​**  ​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.+  - **Zip Install File:​** ​When you are finished with all of these files, create a `.zip` archive from the Plug In Action ​Folder.
  
-==== PIA Folder ====+==== Plug In Action ​Folder ====
  
  
-**A _Plug In Action_ is Contained in a Folder**,\\ **Whose Name:**+**A _Plug In Action_ is Contained in a Folder**, **Whose Name:**
   - Should generally closely match the action name   - Should generally closely match the action name
   - Must be made up of only ASCII alphanumerics,​ underscores and spaces.   - Must be made up of only ASCII alphanumerics,​ underscores and spaces.
Line 59: Line 59:
   - 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 Plug In Action ​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 67: Line 67:
   - Icon File: 64x64 png icon (optional).   - Icon File: 64x64 png icon (optional).
  
-**The PIA Folder must be stored as a `.zip` archive file for installation.**+**The Plug In Action ​Folder must be stored as a `.zip` archive file for installation.**
  
-==== PIA PList ====+==== Plug In Action ​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:
  
 ^ Key ^ Description ^ ^ Key ^ Description ^
-^ Name | Name of the action.\\ (which appears in the Category/​Actions list) | +^ Name | **Name of the action**.\\ (which appears in the Category/​Actions list) | 
-^ Script | Name of the script file which will be run when the PIA is executed.\\ ​ The name can only use ASCII alphanumerics or underscores,​ plus an ASCII alphanumeric extension | +^ Script | **Name of the script file** which will be run when the Plug In Action ​is executed.\\ ​ The name can only use ASCII alphanumerics or underscores,​ plus an ASCII alphanumeric extension | 
-^ Parameters | An array of parameters to the script, each entry is a dictionary [[Plug_In_Actions#​Plist_Parameters|as described below]].\\  These parameters will appear as form fields in the PIA in the Keyboard Maestro Editor.\\ They allow the user of the PIA to enter the data to be processed by the script. ​\\ **Optional** | +^ Parameters | **An array of parameters to the script**<​WRAP>​ 
-^ Icon | Name of the icon png file, made up of only ASCII alphanumerics or underscores plus .png \\ **Optional** | +  * Each entry is a dictionary [[Plug_In_Actions#​Plist_Parameters|as described below]]. 
-^ Title | 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 \\ **Optional** | +  These parameters will appear as form fields in the Plug In Action ​in the Keyboard Maestro Editor. 
-^ Timeout | The default timeout in seconds, entered ​as a _number_.\\ Set it to 0 if the action needs no timeout.\\  The default is 99 hours\\  Like all Actions, Timeout can be changed in the _Editor_.\\ **Optional** |+  * They allow the user of the Plug In Action ​to enter the data to be processed by the script. 
 +  *  ​**Optional** 
 +</​WRAP> ​
 +^ Icon | **Name of the icon png file**, made up of only ASCII alphanumerics or underscores plus .png \\ **Optional** | 
 +^ Title | **The title displayed on the action**<​WRAP>​ 
 +  * Which can include %Param%XYZ% tokens. 
 +  * It should usually not include other tokens. 
 +  * If it is missing, the Name will be used
 +  * **Optional** 
 +</​WRAP> ​
 +^ Timeout | **The default timeout in seconds**<​WRAP>​ 
 +  * Entered ​as a _number_ 
 +  * Set it to 0 if the action needs no timeout 
 +  The default is 99 hours 
 +  Like all Actions, Timeout can be changed in the _Editor_ 
 +  * **Optional** 
 +</​WRAP> ​|
 ^ Author | The author of this action \\ **Optional** | ^ Author | The author of this action \\ **Optional** |
 ^ URL | URL for the author or this action \\ **Optional** | ^ URL | URL for the author or this action \\ **Optional** |
 ^ Help | A short (Tool Tip) explanation of this action \\ **Optional** | ^ Help | A short (Tool Tip) explanation of this action \\ **Optional** |
-^ Results | What to do with the output of the script if any.\\ Possible Values: NoneWindowBrieflyTypingPastingVariableClipboard ​– multiple ​values can be used, separated by a bar (%%|%%), the first specified value is the default \\ **Optional** |+^ HelpURL | A URL for the Help link for the action (v11.0+) \\ **Optional** | 
 +^ Results | **What to do with the output of the script if any**.\\ Possible Values:<​WRAP>​ 
 +  * None 
 +  * Window 
 +  * Briefly 
 +  * Large 
 +  * Typing 
 +  * Pasting 
 +  * Variable 
 +  * AppendVar 
 +  * Clipboard 
 +  * File 
 +  * Asynchronously 
 +</​WRAP>​ Multiple ​values can be used, separated by a bar (%%|%%), the first specified value is the default. If output is going to a clipboard or a file, the results can be an image. ​\\ **Optional** |
  
 ==== Plist Parameters ==== ==== Plist Parameters ====
  
 +^ Parameter Key ^ Description ^
 +^ Label | **Name of the parameter**.<​WRAP>​
 +  * 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 ​
 +</​WRAP>​ |
 +^ Type | **Type of the parameter**.\\ Must be one of the following:​\\ _(Text in italics is info, and not part of the Type)_<​WRAP>​
 +  * String _(single line)_
 +  * TokenString
 +  * Calculation
 +  * Text _(multi-line)_
 +  * TokenText
 +  * Checkbox _(0 or 1)_
 +  * PopupMenu
 +  * Hidden
 +</​WRAP> ​ 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 | Values of the popup menu, separated by %%|%%\\ **Optional** unless Type is _PopupMenu_. |
 +^ Default | Default value of the Parameter ​ when the Plug In Action is inserted in the Macro.\\ **Optional** |
  
 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:
  
-^ Parameter Key ^ Description ^ 
-^ Label | **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 | 
-^ Type | **Type of the parameter**.\\ Must be one of the following:​\\ _(Text in italics is info, and not part of the Type)_\\ • String _(single line)_\\ • TokenString\\ • Calculation\\ • Text _(multi-line)_\\ • TokenText\\ • Checkbox _(0 or 1)_\\ • PopupMenu\\ • 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 | Values of the popup menu, separated by %%|%%\\ **Optional** unless Type is _PopupMenu_. | 
-^ Default | Default value of the Parameter ​ when the PIA is inserted in the Macro.\\ **Optional** | 
  
 Warning: Keys are case sensitive. Warning: Keys are case sensitive.
Line 102: Line 144:
  
  
-_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. ​ +_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.\\ +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.  ​
-Note that `spaces` in the variable names _must_ be replaced with `underscores` in your script.  ​+
  
  
-**Methods To Retrieve Parameters**+**Methods To Retrieve Parameters ​Using AppleScript**
  
 <code applescript>​ <code applescript>​
Line 142: Line 183:
 </​code>​ </​code>​
  
-==== Reload to Use Updated ​PIAs ====+==== Reload to Use Updated ​Plug In Actions ​====
  
  
Line 152: Line 193:
 </​code>​ </​code>​
  
-==== PIA Failure ====+==== Plug In Action ​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, potentially aborting the macro.
  
manual/Plug_In_Actions.1622567603.txt.gz · Last modified: 2021/06/01 13:13 by JMichaelTX