Intro to the Run JavaScript on Web Page action in Shortcuts on iPhone or iPad
Nearly all web pages are scripted using JavaScript, a programming language that creates dynamic effects in web browsers, including animations, interactive menus, video playback and more. Generally, JavaScript isn’t exposed to you as you view a website. However, by building a shortcut that contains the Run JavaScript on Web Page action and then running the shortcut from the Safari app, you can control a web page’s JavaScript.
Shortcuts that run your custom JavaScript on a web page have myriad uses. For example, you can create shortcuts that retrieve specific data from a web page and then incorporate that data into a task, such as extracting a class schedule and then adding it to the Calendar app, or exporting the membership data of a social media group and then adding that data to a spreadsheet.
You can also create shortcuts that let you modify a web page, such as changing the font of the web page’s text or modifying the speed at which a video plays back. Before you can run JavaScript from a shortcut, you must enable the setting. See Advanced Privacy and security settings in Shortcuts on iPhone or iPad.
For information on using shortcuts that run JavaScript on a web page, see Use the Run JavaScript on Web Page action in Shortcuts on iPhone or iPad.
About retrieving web page data
The Run JavaScript on Web Page action lets you retrieve data from a web page by grabbing all elements that match certain criteria, then iterating through those elements to perform a task with the data (or to inspect the elements further).
For example, to create a list of every image element on a web page, use:
var elements = document.querySelectorAll("img");
In another example, to retrieve every element with the class “post”, use:
var elements = document.querySelectorAll(".post");
Once a NodeList is created, you can iterate through the elements (to further filter the elements or add the elements to a data structure) using something like:
var elements = ...;for (let element of elements) { // ...}For more information on querying web page results, see https://developer.mozilla.org/Selectors and https://developer.mozilla.org/SelectorAll.
Run JavaScript on Web Page action input
The input to the Run JavaScript on Web Page action must be an active Safari web page, which means you must run the shortcut from the share sheet (specifically from Safari, SFSafariViewController or ASWebAuthenticationSession).
When a shortcut is run from the share sheet, the input from the Safari app is passed into the first action of your shortcut.
Although the input into the Run JavaScript on Web Page action must be a Safari web page, you can insert additional data into the action by using Magic Variables. For example, the Change Video Speed shortcut (available in the Gallery) contains a Run JavaScript on Web Page action that modifies a video on a web page. The playback rate of the video is controlled by the Speed variable.
For information on running shortcuts from Safari, see Launch a shortcut from another app on iPhone or iPad.
Run JavaScript on Web Page action output
To return data, you must call the completion handler in JavaScript, such as completion(result). Because JavaScript is usually used with asynchronous patterns, the call is intentionally not synchronous. This way, you can finish the action asynchronously. For example, the following is valid:
window.setTimeout(function() { completion(true);}, 1000);The output of the Run JavaScript on Web Page action is any valid JSON data type, including:
String
Number
Boolean (true or false)
Array (containing any other valid JSON type)
Dictionary (containing any other valid JSON type)
Null
Undefined
Behind the scenes, Shortcuts automatically encodes and decodes your returned value to communicate between JavaScript and the Shortcuts app. This means you don’t need to call JSON.stringify(result) before calling the completion handler.
Because the return value is JSON, certain return values won’t work well. For example, a function or Node won’t have a useful JSON-encoded representation. In this case, it’s recommended you create an Array/Dictionary that contains the JSON-compatible values you need.
Note: Because an object in JavaScript is simply a dictionary, basic objects convert to JSON well.
If you don’t want to return any data from the Run JavaScript on Webpage action, you can call completion() with no argument in the function (because undefined is a valid output). This is identical to calling completion(undefined).
For more information about JSON, see Intro to using JSON in Shortcuts on iPhone and iPad.
For more information on Nodes, see https://developer.mozilla.org/Node.
For more information on functions, see https://developer.mozilla.org/Functions.
Run JavaScript on Web Page action time limit
Like all JavaScript extensions in Safari, the Run JavaScript on Web Page action is subject to a time limit and should be completed as quickly as possible. JavaScript that uses synchronous functions might not complete in time, including:
window.alert()window.prompt()window.confirm()Timeouts that last multiple seconds — for example:
window.setTimeout(function() { completion(); }, 5000);
If your JavaScript exceeds the time limit, the shortcut will fail to complete and a JavaScript Timeout error message will appear when you run the shortcut.
Syntax and Runtime Error Handling
You can use any syntax that’s supported in Safari to write JavaScript in the Run JavaScript on Web Page action.
In the Shortcuts app, the Run JavaScript on Web Page action helps you spot errors by doing a basic syntax check before you run the shortcut from the Safari extension.
As you enter your script in the text field, syntax highlighting helps ensure that your JavaScript is valid. For example, if you forget to include quotation marks at the end of a string, all the text following that string is highlighted.
If your script’s syntax is valid but contains a runtime error, the Run JavaScript on Web Page action catches and displays the exceptions. For example, if your script references a variable or function that doesn’t exist (such as shortcuts.completion()), an error is displayed at runtime.