Differences

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

--- JXA_JavaScript_for_Applications [2016/01/05 20:11] – [Attaching reusable names to evaluations and their results:] ComplexPoint
+++ JXA_JavaScript_for_Applications [2016/01/07 02:17] (current) – deleted in favor of JavaScript for Automation peternlewis
@@ Line 1: / Line 1: @@
-====== Using JavaScript for Automation (JXA) with Keyboard Maestro ======
-=====Executing JavaScript from KM – which action ?=====
-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).
-[[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:
-. 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.
-The first script to try in JXA consists of just one word:
-`this`
-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.
-{{:undefined:jxaactionthis.png?400|}}{{:undefined:jxashellactionthis.png?400|}}
-Later on, you may find it interesting to scan this output list for useful functions, but for the moment, it's enough to simply notice that the JXA JavaScript environment is very different from the set of web page (window and document) references that you find in the Browser JavaScript environments of Chrome and Safari.
-{{: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.
-=====The basics – AppleScript and JavaScript for Automation side by side=====
-====Evaluating simple expressions====
-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:
-- 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).
-^ AppleScript    ^ JXA  ^
-| <code>((sqrt 5) + 1) / 2    </code> | <code>(Math.sqrt(5) + 1) / 2    </code> |
-{{:mathexpressionas.png|}}{{:mathexpressionjs.png|}}
-==Differences to notice: sqrt 5 vs Math.sqrt(5)==
-JavaScript's [[https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Math|Math object]] provides a number of numeric functions and constants, in the format **Math.***functionName*(''[argument, …]'').
-In the common JavaScript patterns:
-- **ObjectName**.*functionName*(''[argument, …]'')
-- **ObjectName**.*propertyName*
-The dot corresponds to Applescript's ''of'', reversing the sequence of object name and property name.
-^ AppleScript    ^ JXA  ^
-| <code>count of documents of application "TextEdit"    </code> | <code>Application("TextEdit").documents.length    </code> |
-====Attaching reusable names to evaluations and their results:====
-If we often need to calculate the [[https://en.wikipedia.org/wiki/Golden_ratio|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===
-^ AppleScript    ^ JXA  ^
-| <code>on goldenRatio()
-    return ((sqrt 5) + 1) / 2
-end goldenRatio
-class of goldenRatio        </code> | <code>function goldenRatio () {
-    return (Math.sqrt(5) + 1) / 2;
-}
-typeof goldenRatio        </code> |
-{{::ashandlerclass.png|}}{{::jxafunction.png|}}
-In both languages, we can call/run/apply a handler/function (that is, get an evaluation of it), by adding a pair of parentheses to its name. (If the function has an input argument, the argument goes between the parentheses).
-^ AppleScript    ^ JXA  ^
-| <code>on goldenRatio()
-    return ((sqrt 5) + 1) / 2
-end goldenRatio
-goldenRatio()    </code> | <code>function goldenRatio () {
-    return (Math.sqrt(5) + 1) / 2;
-}
-goldenRatio()</code>|
-{{::ascallsyntaxcoded.png|}}{{::calljxa.png|}}
-==Differences to notice: 1. Separating expressions – AppleScript newline vs JavaScript semicolon==
-JavaScript is more flexible with white space than AppleScript – a JS expression can be broken up over several lines, if that makes its structure clearer, while a new line is interpreted as the **end** of an AppleScript expression.
-In JavaScript, a semicolon means 'end of expression'.
-==Differences to notice: 2. Returning a value from a handler / function==
-In AppleScript, the word **return** in the handler is optional – if you omit it, the value of the last expression to be evaluated inside the handler will still be returned.
-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===
-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.
-^ AppleScript    ^ JXA  ^
-| <code>on goldenRatio(n)
-    return (((sqrt 5) + 1) / 2) * n
-end goldenRatio
--- For a square of side 8
-goldenRatio(8)
--- --> 12.944271909999</code> | <code>function goldenRatio (n) {
-    // n is optional here – defaults to 1
-    n = n || 1;
-    return ((Math.sqrt(5) + 1) / 2) * n;
-}
-// For a square of side 8
-goldenRatio(8);
-// --> 12.94427190999916</code>|
-==Differences to notice: 1. Comments==
-Both languages allow us to include explanatory comments. AS prefixes comments with two dashes, JS with two forward slashes.
-==Differences to notice: 2. Arguments can be optional in JavaScript==
-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===
-(to be added)