Differences

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

--- JavaScript_for_Automation [2016/02/20 20:38]
ComplexPoint [Indexing by number: AS lists ⇄ JS arrays]
+++ JavaScript_for_Automation [2019/01/12 12:43] (current)
JMichaelTX [Accessing Keyboard Maestro Variables] ADD Link to Get/Set Local/Instance Vars
@@ Line 1: / Line 1: @@
-====== Using JavaScript for Automation (JXA) with Keyboard Maestro ======
+====== JavaScript for Automation (JXA) Discussion ======
-=====Executing JavaScript from KM – which action ?=====
+===== Scope and Summary =====
+This Wiki article is a broad topic, which covers these major areas:
+  - Introduction to JXA
+  - Using JXA with Keyboard Maestro
+  - JXA Background
+  - Comparison with AppleScript
+===== Introduction =====
+Keyboard Maestro supports use of JavaScript in two basic ways:
+  - Execute JavaScript in a Browser
+  - Execute JavaScript for Automation (JXA)
+This article deals only with the latter, JavaScript for Automation (JXA).
 JavaScript, once a language which ran only in web browsers, can now be used in a variety of environments. From Keyboard Maestro you can:
 . Run it in Chrome or Safari web pages ('browser JavaScript'), or
-. (in OS X Yosemite onwards) run it in Apple's osascript environment, for automating applications. ('JavaScript for Automation', or JXA, sometimes JSA in Apple's documentation).
+. Run it in Apple's osascript environment, for automating applications. ('JavaScript for Automation', or JXA, sometimes JSA in Apple's documentation), or
+. Run it in Custom HTML Prompt windows.
-[[https://developer.apple.com/library/mac/releasenotes/InterapplicationCommunication/RN-JavaScriptForAutomation/Articles/Introduction.html|JavaScript for Automation]] (JXA) is a more flexible alternative to AppleScript, with a richer set of default libraries for some basics like regexes and URL handling. Its equivalent of AppleScript 'records' is more forgiving and much easier to use. JXA is the same fast JavaScript Core language that Safari uses, but it is running in an osascript context:
+=====Using JXA with Keyboard Maestro=====
+==== JXA Scripts ====
+You can run a JXA script from Keyboard Maestro by either of these _Execute Script_ Actions:
+  * [[action:Execute_a_JavaScript_For_Automation]]
+    * The JXA script may be accessed as text in the Action, or from a file.
+  * [[action:Execute_a_Shell_Script|Execute a Shell Script]]
+    * The JXA script can be embedded in a Shell Script
+==== Accessing Keyboard Maestro Variables ====
+You can access Keyboard Maestro variables (7.1+) from JXA scripts using the Keyboard Maestro Engine application.
+<code javascript>
+//--- GET A REFERENCE TO THE KM ENGINE ---
+var kme = Application("Keyboard Maestro Engine");
+//--- GET A KM VARIABLE ---
+var myVar = kme.getvariable('My KM Var');
+//--- SET A KM VARIABLE ---
+//    - Using explicit text
+kme.setvariable('My Other KM Var', { to: "Set by JXA" });
+//    - Using a JavaScript Variable
+var scriptResults = "Text Determined by the script"
+kme.setvariable('My Other KM Var', { to: scriptResults });
+</code>
+Also see **[[action:Execute_a_JavaScript_For_Automation#Local_Instance_Variables|How To Get/Set Keyboard Maestro Local & Instance Variables using JXA]]**
+JXA can get a list of all variables as described on the [forum](https://forum.keyboardmaestro.com/t/using-km-variables-in-yosemite-javascript-for-applications-jxa/889) and those methods also provide more convoluted ways to access variables for versions prior to 7.1.
+**For more info on using JXA with Keyboard Maestro, see:**
+  * [[manual:Scripting|Scripting]]
+===== JXA Background =====
+[[https://developer.apple.com/library/mac/releasenotes/InterapplicationCommunication/RN-JavaScriptForAutomation/Articles/Introduction.html|JavaScript for Automation]] (JXA) and AppleScript are the two primary languages Apple has provided for application automation.  While they both can generally achieve the same results, each language offers advantages and disadvantages.  JXA is very flexible providing a rich set of default libraries for some basics like character, date, and URL handling.  It also offers a very powerful Regular Expression engine built-in.  JXA is the same fast JavaScript Core language that Safari uses, but it is running in an osascript context:
 . With access to the functions and constants of an Automation object, and
-. with additional access to a lot of low-level Apple system functions through the ObjC object.
+. with additional access to a lot of low-level Apple system functions through the Objective-C object.
-The first script to try in JXA consists of just one word:
+You can view the built-in, default function provided by JXA by running this simple, one-word script:
 `this`
@@ Line 19: / Line 80: @@
 the result will be a listing of all the pre-defined names in JXA's osascript environment.
-We can either run this directly from from one of KM's 'Execute a JavaScript for Automation' actions, or use an osascript command in an Execute Shell Script action.
+We can either run this directly from from one of Keyboard Maestro's 'Execute a JavaScript for Automation' actions, or use an osascript command in an Execute Shell Script action.
 {{:undefined:jxaactionthis.png?400|}}{{:undefined:jxashellactionthis.png?400|}}
@@ Line 27: / Line 88: @@
 {{:chromwinkeys.png?400|}}{{:undefined:jssafariactiondocument.png?400|}}
-Keyboard Maestro's 'Execute a JavaScript in Safari' and 'Execute a JavaScript in Google Chrome' actions are for interacting with web pages, whereas JXA is for automating OS X and OS X Applications.
+Keyboard Maestro’s [[action:Execute a JavaScript in Safari|Execute a JavaScript in Safari]] and [[action:Execute a JavaScript in Google Chrome|Execute a JavaScript in Google Chrome]] actions are for interacting with web pages, the [[action:Execute a JavaScript in Custom Prompt|Execute a JavaScript in Custom Prompt]] action is for interacting with Custom HTML Prompts, whereas JXA is for automating OS X and OS X Applications via the [[action:Execute a JavaScript For Automation|Execute a JavaScript For Automation]] action.
-=====The basics – AppleScript and JavaScript for Automation side by side=====
+=====Comparing JXA with AppleScript=====
 ====Evaluating simple expressions====
@@ Line 35: / Line 97: @@
 The simplest scripts evaluate an expression and return its value.
-**NB** KM Maestro can only make use of values returned as (or converted to) a string – a KM variable is always a string of some kind. This means that:
+**NB** Keyboard Maestro can only make use of values returned as (or converted to) a string – a Keyboard Maestro variable is always a string of some kind. This means that:
 - If the result of an evaluation is not a string (or something simple like a number, that can automatically be converted to a string), the action may puzzle you by appearing to produce no result.
 - It's a good idea to test your action code first in (El Capitan or Yosemite) Script Editor, which shows all results, whatever their type, including error messages.
-The following all return the same number to KM (in string format, and at a slightly higher level of precision – more decimal points – from JavaScript).
+The following all return the same number to Keyboard Maestro (in string format, and at a slightly higher level of precision – more decimal points – from JavaScript).
 ^ AppleScript    ^ JXA  ^
@@ Line 61: / Line 123: @@
 | <code applescript>count of documents of application "TextEdit"    </code> | <code javascript>Application("TextEdit").documents.length    </code> |
-====Attaching reusable names to computations and their results:====
+====Assigning names to functions and procedures:====
 If we often need to calculate the [[https://en.wikipedia.org/wiki/Golden_ratio|Golden Ratio]], we can attach a name to its computation, and reuse it by that name. Nameable computations are called 'handlers' in AppleScript, and 'functions' in JavaScript.
-===Named computations – handlers and functions===
+===Named AS 'handlers' and JS functions===
 ^ AppleScript    ^ JXA  ^
@@ Line 105: / Line 167: @@
 In JavaScript, however, a function only returns what you ask it to. If you don't use the **return** keyword, the function evaluates to the special value ''undefined'', and your Keyboard Maestro action will just get an empty string. Always include a **return** line.
-===Parameters / arguments for named computations===
+===Parameters / arguments for name functions===
 If you are building a well-proportioned temple or table, you will probably want to multiply the Golden Ratio by something else, so a named computation with a variable 'parameter' or 'argument' might make sense.
@@ Line 140: / Line 202: @@
 JavaScript is relaxed about whether we supply an argument or not. If we don't, the name ''n'' will have the special value ''undefined'', which takes on the value ''false'' in a logical expression. Above we are using the [[https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Logical_Operators|JavaScript logical operator OR ( || )]] to attach the name n to the value 1 if no argument has been supplied.
-===Named results of computations – 'variables' which hold values===
+===Named results – 'variables' which hold values===
 In addition to reusable names for particular computations and their arguments, we can also give names to the results of computations. Once a result is stored in a named variable, we can reuse it without having to recalculate it.
@@ Line 238: / Line 300: @@
 .concat(["gamma", "delta"])
 // ["alpha", "beta", "gamma", "delta"]</code>|
-^ AppleScript join (user-defined)  ^ JavaScript join (built in) ^
+^ AppleScript join() (user-defined)  ^ JavaScript join() (built in) ^
 |<code applescript>join(" -> ", {"Sun", "Mon", "Tue"})
@@ Line 253: / Line 315: @@
 // "Sun -> Mon -> Tue
@@ Line 263: / Line 321: @@
 //  of JavaScript arrays
 </code>|
 ====Indexing by name – AS records and JS objects====
 to follow ...
-====Structuring computations – branching, repetition, and nested composition====
+====Structuring scripts – branching, nesting, mapping, filtering and reducing====
 to follow ...
@@ Line 274: / Line 334: @@
 to follow ...
-=====The Automation interface=====
-===Using the Standard Additions library====
-to follow ...
-===Interacting with scriptable applications===
+===== See Also =====
-to follow ...
+----
-=====Using the Safari JSContexts Debugger (El Capitan onwards)=====
+=== Actions ===
-to follow ...
+* [[action:Execute a JavaScript For Automation|Execute a JavaScript For Automation]]
+* [[action:Execute a JavaScript in Custom Prompt|Execute a JavaScript in Custom Prompt]]
+* [[action:Execute a JavaScript in Google Chrome|Execute a JavaScript in Google Chrome]]
+* [[action:Execute a JavaScript in Safari|Execute a JavaScript in Safari]]
+* [[:Actions|See all Actions]]
-=====The ObjC interface=====
+----
-to follow ...
+==== Forum ====
-===Basic file functions===
+- [[https://forum.keyboardmaestro.com/t/using-km-variables-in-yosemite-javascript-for-applications-jxa/889|Using KM variables in Yosemite Javascript for Applications (JXA)]]
+- [[https://forum.keyboardmaestro.com/t/how-to-change-safari-web-inspector-font/3655|How to Change Safari Web Inspector Font]]
-to follow ...
+- [[https://forum.keyboardmaestro.com/tags/jxa|Keyboard Maestro Forum topics about JavaScript for Automation]]
-===Clipboard functions===
-to follow ...
-===Reading the documentation for simple ObjC functions===
-to follow ...

Keyboard Maestro Wiki

User Tools

Site Tools

Differences

Page Tools