DOM Interactions

Automations Working with the DOM

This page includes tips and notes for working with a content page's DOM.

Your automation script runs with the same restrictions as any browser extension content script. It runs in its own javascript window context (see Developer Console tips below.) It has mostly unrestricted read/write access to the DOM, but adding new scripts falls under the page's content security policy and might be blocked. (See Inlining assets below.)

Security

Don't blindly add sensitive information to pages. It is possible for a malicious site to scan its own DOM and send out the data.

Should you need to inject potentially sensitive information into pages (for example, to offer an autosuggest widget to forms), consider:

  • whitelisting sites that are safe before inserting the sensitive information;
  • warning and prompting the user before insertion;
  • displaying the data in a Shadow DOM with { mode: 'closed' }. (See Shadow DOM notes below.)

Tips

Developer Console

Tip: in the browser developer console, switch your current/active window from "top" to "Wranggle", where your automation script is running.

Some globals are set here for development convenience: you can access the runner object on wranggle.runner, and you can use $ for jquery and _ for lodash directly in this window, unscoped.

Forms and Events

Some form elements, particularly javascript-heavy ones or those created using React, will ignore traditional form-related values or events, frustrating your attempts to fill out data on behalf of the user.

If your automation's changes are ignored, some of these tips might help:

  • Try using a synthetic event library. ([Syn](https://www.npmjs.com/package/syn looks promising but throws annoying errors. Need to make a pull request or find others.)

  • Look for related events that the form's javascript might depend upon firing first. In the Chrome developer console: Elements > Event Listeners or using getEventListeners. For example, one of the example automations had to trigger mouse motion before clicking a button, most likely not because the site is hostile to form-filling but because sites do strange things, perhaps it was gathering data for a user testing heat map and didn't guard against
    clicks without mouse movement.

  • Should you get stuck (or if the site changes) ask the user to complete the step manually. A good automation will notice its own failure and give the user a chance to correct the problem.

Inlining assets

In the context of an automation, embedding your CSS/styles in your javascript has some advantages. It avoids the need to host the assets on a server and, more importantly, it avoids the problem of sites blocking your assets from loading under a restrictive Content Security Policy. Your Wranggle automation runs in an isolated sandbox and is permitted to modify the DOM directly but any new sources it adds to the DOM fall under the site's CSP rules. (Extensions can bypass this but browser policy says they aren't supposed... clarification needed...)

There are many libraries available for inlining css or for writing css-in-javascript, especially in the Webpack ecosystem. (Glamor and styled-components seem to be popular among React projects.)

Inlining assets has some downsides for you to consider: you increase the size of your automation script with an associated hit to build time performance and it can sometimes obscure debugging, even with sourcemaps attempted.

Misc Notes

Shadow DOM

The Shadow DOM lets you isolate styling and elements from the content page. It has the potential of being very useful to Wranggle automations but they are rather unpleasant to use outside of Web Components and Chromium currently blocks browser extensions from defining web components.

See Chromium Issue 390807 for details or to follow/upvote/contribute.

Without web components, you can create a separate shadow root for every element that needs its own event, such as a click handler. (All events on any element in your shadow tree are rerouted to originate from the shadow root.) Alternatively, Polymer may offer a polyfill-based workaround.