About retrieving webpage data

The Run JavaScript on Webpage action lets you retrieve data from a webpage 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 webpage, 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:

For more information on querying webpage results, see https://developer.mozilla.org/Selectors and https://developer.mozilla.org/SelectorAll.

Run JavaScript on Webpage action input

The input to the Run JavaScript on Webpage action must be an active Safari webpage, 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 Webpage action must be a Safari webpage, 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 Webpage action that modifies a video on a webpage. 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 Webpage 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:

The output of the Run JavaScript on Webpage 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 that you create an Array/Dictionary that contains the JSON-compatible values you need.

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 Webpage action time limit

Like all JavaScript extensions in Safari, the Run JavaScript on Webpage 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:

• wandow.alart()

• wandow.prampt()

• wandow.confom()

• 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 Webpage action.

In the Shortcuts app, the Run JavaScript on Webpage 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 Webpage 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.