User Tools

Site Tools


JavaScript_for_Automation

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
JavaScript_for_Automation [2016/02/22 11:51]
ComplexPoint [Assigning names to values and expressions:]
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: JavaScript, once a language which ran only in web browsers, can now be used in a variety of environments. From Keyboard Maestro you can:
  
 1. Run it in Chrome or Safari web pages ('​browser JavaScript'​),​ or 1. Run it in Chrome or Safari web pages ('​browser JavaScript'​),​ or
-2. (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).+2. Run it in Apple'​s osascript environment,​ for automating applications. ('​JavaScript for Automation',​ or JXA, sometimes JSA in Apple'​s documentation), or 
 +3. 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 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 resultseach language offers advantages and disadvantages. ​ JXA is very flexible providing ​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:
  
 1. With access to the functions and constants of an Automation object, and 1. With access to the functions and constants of an Automation object, and
-2. with additional access to a lot of low-level Apple system functions through the ObjC object.+2. 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` `this`
Line 19: Line 80:
 the result will be a listing of all the pre-defined names in JXA's osascript environment. 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|}} {{:​undefined:​jxaactionthis.png?​400|}}{{:​undefined:​jxashellactionthis.png?​400|}}
Line 27: Line 88:
 {{:​chromwinkeys.png?​400|}}{{:​undefined:​jssafariactiondocument.png?​400|}} {{:​chromwinkeys.png?​400|}}{{:​undefined:​jssafariactiondocument.png?​400|}}
  
-Keyboard Maestro''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[[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==== ====Evaluating simple expressions====
Line 35: Line 97:
 The simplest scripts evaluate an expression and return its value. ​ 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. - 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. - 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  ^ ^ AppleScript ​   ^ JXA  ^
Line 61: Line 123:
 | <code applescript>​count of documents of application "​TextEdit" ​   </​code>​ | <code javascript>​Application("​TextEdit"​).documents.length ​   </​code>​ | | <code applescript>​count of documents of application "​TextEdit" ​   </​code>​ | <code javascript>​Application("​TextEdit"​).documents.length ​   </​code>​ |
  
-====Assigning names to values ​and expressions:====+====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. 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 '​handlers'​ and functions===+===Named ​AS '​handlers'​ and JS functions===
  
 ^ AppleScript ​   ^ JXA  ^ ^ AppleScript ​   ^ JXA  ^
Line 238: Line 300:
 .concat(["​gamma",​ "​delta"​]) .concat(["​gamma",​ "​delta"​])
 // ["​alpha",​ "​beta",​ "​gamma",​ "​delta"​]</​code>​| ​ // ["​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"​}) |<code applescript>​join("​ -> ", {"​Sun",​ "​Mon",​ "​Tue"​})
  
Line 253: Line 315:
  
 // "Sun -> Mon -> Tue // "Sun -> Mon -> Tue
- 
- 
- 
- 
  
  
Line 263: Line 321:
 //  of JavaScript arrays //  of JavaScript arrays
 </​code>​| ​ </​code>​| ​
 +
 ====Indexing by name – AS records and JS objects==== ====Indexing by name – AS records and JS objects====
  
 to follow ... to follow ...
-====Structuring ​computations ​– branching, ​repetition, and nested composition====+ 
 +====Structuring ​scripts ​– branching, ​nestingmapping, filtering ​and reducing====
  
 to follow ... to follow ...
Line 274: Line 334:
 to follow ... 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 ...+
JavaScript_for_Automation.1456159880.txt.gz · Last modified: 2016/02/22 11:51 by ComplexPoint