Differences

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

--- action:Execute_a_JavaScript_For_Automation [2017/04/05 21:04] – Replaced example script, added script for dialogs JMichaelTX
+++ action:Execute_a_JavaScript_For_Automation [2025/08/18 02:17] (current) – [Local & Instance Variables] peternlewis
@@ Line 16: / Line 16: @@
   *Asynchronously ignored — the action runs while the macro continues on.
+By default, errors are not included in the output, and the output is trimmed of white space. These can be adjusted in the action (gear) ⚙ menu.
-===== Get/Set Keyboard Maestro Variables =====
+===== Modern Syntax =====
+In version 11.0, scripts default to Modern Syntax, which essentially wraps the script in:
-** Example JXA Script shows how to Get/Set Keyboard Maestro Variables, and Get/Set the System Clipboard.**
 ```javascript
-'use strict';
+(function () {
-(function run() {      // this will auto-run when script is executed
+…
+})()
+```
-  // --- SET CURRENT APP VARIABLE NEEDED FOR DIALOGS & StandardAdditions.osax ---
+This helps keep your script from interacting with the web page in unexpected ways. A result of this is that you need to return values to the action using the `return` syntax. So a trivial action would be:
-  var app = Application.currentApplication()
-  app.includeStandardAdditions = true
-  // --- SET KME APP VARIABLE NEEDED TO GET/SET KM VARIABLES ---
+```javascript
-  var kme = Application("Keyboard Maestro Engine");
+return "Hello";
+```
+You can turn Modern Syntax on or off in the popup menu next to the script.
+{{:action:modern-syntax.png?nolink|}}
+===== Using Keyboard Maestro Variables =====
+In Modern Syntax (v11.0+), reference the variable like this:
+```javascript
+var v = kmvar.My_KM_Data
+```
+Alternatively, the variables are stored in the environment variables with a prefix of `KMVAR_`.
+When accessing a variable, if its name has a space in it, replace it with an underscore.
+Local and Instance variables are available, but Password variables are not.
+By default, all variables are included, but you can select No Variables, or specific variables as desired using the popup menu next to the script.
+==== Using JXA to Access Variables ====
+You can use JXA’s ability to communicate with the Keyboard Maestro Engine to read and write variables.
+```javascript
+// Assumes Modern Syntax
+// --- SET CURRENT APP VARIABLE NEEDED FOR DIALOGS & StandardAdditions.osax ---
+var app = Application.currentApplication()
+app.includeStandardAdditions = true
-  //--- GET A KM VARIABLE ---
+// --- SET KME APP VARIABLE NEEDED TO GET/SET KM VARIABLES ---
-  //    Returns empty string if it doesn't exist
+var kme = Application("Keyboard Maestro Engine");
-  var someVarNameStr = kme.getvariable("KMVarNameToGet") || 'Default Value if NOT Found';
-  console.log("someVarNameStr: " + someVarNameStr)
-  var someNewDataStr = "Text to be set to a KM var";
+//--- GET A KM VARIABLE ---
+//    Returns empty string if it doesn't exist
+var someVarNameStr = kme.getvariable("KMVarNameToGet") || 'Default Value if NOT Found';
+console.log("someVarNameStr: " + someVarNameStr)
-  //--- SET A KM VARIABLE ---
+var someNewDataStr = "Text to be set to a KM var";
-  //      Creates the Variable if it doesn't exist
-  //      Verify Variable in the KM App Preferences
+//--- SET A KM VARIABLE ---
-  kme.setvariable("KMVarNameToSet", { to: someNewDataStr });
+//      Creates the Variable if it doesn't exist
+//      Verify Variable in the KM App Preferences
+kme.setvariable("KMVarNameToSet", { to: someNewDataStr });
-  //--- GET TEXT ON CLIPBOARD ---
+//--- GET TEXT ON CLIPBOARD ---
-  var clipboardStr = app.theClipboard()
+var clipboardStr = app.theClipboard()
-  console.log("clipboardStr: " + clipboardStr)
+console.log("clipboardStr: " + clipboardStr)
-  var someDataStr = "Example text to put on clipboard"
+var someDataStr = "Example text to put on clipboard"
-  //--- COPY TO CLIPBOARD ---
+//--- COPY TO CLIPBOARD ---
-  //      Verify using KM Clipboard History Viewer
+//      Verify using KM Clipboard History Viewer
-  app.setTheClipboardTo(someDataStr)
+app.setTheClipboardTo(someDataStr)
+```
+==== Local & Instance Variables ====
-}  // END of function run()
+Keyboard Maestro has [[manual:Variables#Instance_Variables_v8|Local and Instance Variables]].  In order to get or set these, you need to have the instance information of the macro and use different parameters in the JXA get/set methods.
-)();
+```javascript
+var app = Application.currentApplication()
+app.includeStandardAdditions = true
+var kmInst = app.systemAttribute("KMINSTANCE");
+var kmeApp = Application("Keyboard Maestro Engine")
+var myLocalVar = kmeApp.getvariable("Local__MyVar",  {instance: kmInst});
+kmeApp.setvariable("Local__FromJXA", {instance: kmInst, to: "Set in JXA Script"})
 ```
----
+Note that this method is only useful if you are not using Modern Syntax (since you can access the local variables directly through the `kmvar` hash), and you need the instance information by some means (passed as an environment variable in the case of the `Execute a JavaScript For Automation` action, but in other cases external to the Keyboard Maestro Engine you would need some other method of getting it).
 ===== Displaying User Dialogs =====
@@ Line 69: / Line 115: @@
 ```javascript
-'use strict';
-(function run() {      // this will auto-run when script is executed
 // --- SET CURRENT APP VARIABLE NEEDED FOR DIALOGS & StandardAdditions.osax ---
 var app = Application.currentApplication()
@@ Line 95: / Line 138: @@
 return ("Btn: " + BtnStr)
-}  // END of function run()
-)();
 ```
+===== See Also =====
-**For more information, see:**
   * [[::JavaScript for Automation]] Wiki Discussion
   * [Forum Topics tagged with "JXA"](https://forum.keyboardmaestro.com/tags/jxa)
   * [Learning & Using AppleScript & JavaScript for Automation (JXA)](http://forum.keyboardmaestro.com/t/learning-using-applescript-javascript-for-automation-jxa/1545)