Differences

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

--- documentation:Plug_In_Actions [2016/05/30 06:42] – created peternlewis
+++ documentation:Plug_In_Actions [Unknown date] (current) – removed - external edit (Unknown date) 127.0.0.1
@@ Line 1: / Line 1: @@
-====== Plug In Actions ======
-Keyboard Maestro has support for user written and contributable plug in actions.  You can get more plug in actions from [[http://www.stairways.com/action/linkthru?thirdpartyactions|our web site]] or [[http://forum.keyboardmaestro.com/c/plugin|the forum]] and you can create and optionally contribute your own.  You can drop a new plug in action .zip archive on the Keyboard Maestro application dock icon to install it (note that to update a plug in action you must manually remove it from the FILE{{{~/Library/Application Support/Keyboard Maestro/Keyboard Maestro Actions}}} folder before re-installing it).
-A Third Party Plug In Action consists of a folder with a name (which should generally closely match the action name), and must be made up of only ASCII alphanumerics, underscores and spaces. The folder name must be unique among all plug in actions.  The folder name is stored in the Keyboard Maestro Macros.plist to reference the plugin action.
-The folder contains a set of files, including:
-* Keyboard Maestro Action.plist – an XML file describing the action.
-* A script file whose name must be made up of only ASCII alphanumerics or underscores, plus an ASCII alphanumeric extension.  It may be a shell script or an AppleScript.  If it is a shell script, it will be made executable automatically.
-* An optional 64x64 png icon.
-The format of the Keyboard Maestro Action.plist is a Cocoa property list containing a dictionary with the following keys and values:
-| Name | the name of the action (which appears in the Category/Actions list) |
-| Script | the name of the script, made up of only ASCII alphanumerics or underscores, plus an ASCII alphanumeric extension |
-| Icon [optional] | the name of the icon png file, made up of only ASCII alphanumerics or underscores plus .png |
-| 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 |
-| Timeout [optional number] | the default timeout in seconds. Set it to 0 if the action needs no timeout.  The default is 99 hours |
-| Author [optional] | the author of this action |
-| URL [optional] | a URL for the author or this action |
-| Help [optional] | a short (Tool Tip) explanation of 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 |
-| Parameters [optional] | an array of parameters to the script, each entry is a dictionary as described below |
-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 |
-| 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 |
-| 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.
-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:
-<code applescript>
-set myText to do shell script "echo $KMPARAM‗My‗Text"
-</code>
-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:
-<code applescript>
-tell application "Keyboard Maestro" to reload
-tell application "Keyboard Maestro Engine" to reload
-</code>
-Keyboard Maestro Plug In Actions go in the FILE{{{~/Library/Application Support/Keyboard Maestro/Keyboard Maestro Actions}}} folder.