DevTools/Highlighter

This article provides technical documentation about DevTools highlighters.

By highlighter, we mean anything that the DevTools display on top of the content page, in order to highlight an element, set of elements or shapes to users.

The most obvious form of highlighter is the box-model highlighter, whose job is to display the 4 box-model regions on top of a given element in the content page, as illustrated in the following screen capture:

But there can be a wide variety of highlighters. In particular, highlighters are a pretty good way to give detailed information about:

• the exact form of a css shape,
• how a css transform applied to an element,
• where are the color stops of a css gradient,
• which are all the elements that match a given selector,
• ...

Using highlighters

Highlighters run on the debuggee side, not on the toolbox side. This is so that it's possible to highlight elements on a remote device for instance. This means you need to go through the Remote Debugging Protocol to use a highlighter.

The highlighter utils

The easiest way to access the highlighters from toolbox-side DevTools code is by using the highlighter utils, which is conveniently available on the toolbox object. Here is how you can access the utils:

 let hUtils = toolbox.highlighterUtils;

Since the box-model highlighter is the most used type of highlighter (for instance it's displayed when you move your mouse over nodes in the inspector), the utils provides a set of methods to interact with it:

Method	Description
startPicker()	Starts the node picker mode which will highlight every node you hover over in the page, and will change the current node selection in the inspector on click. "picker-node-hovered" and "picker-node-picked" events are sent.
stopPicker()	Stops the node picker mode.
highlighterNodeFront(nodeFront)	Display the box-model highlighter on a given node. NodeFront objects are what the WalkerActor return.
highlightDomValueGrip(valueGrip)	Display the box-model highlighter on a given node, represented by a debugger object value grip.
unhighlight()	Hide the box-model highlighter.

But the box-model highlighter isn't the only type of highlighter, so the highlighter utils provides the following method:

Method	Description
getHighlighterByType(typeName)	Instantiate a new highlighter, given its type (as a String). At the time of writing, the available types of highlighters are: BoxModelHighlighter, CssTransformHighlighter, SelectorHighlighter and RectHighlighter. This returns a promise that resolves to the new instance of protocol.js actor.

The highlighter API

When getting a highlighter via toolbox.highlighterUtils.getHighlighterByType(typeName), the right type of highlighter will be instantiated on the server-side and will be wrapped into a CustomHighlighterActor and that's what will be returned to the caller. This means that all types of highlighters share the same following API:

Method	Description
show(NodeActor node[, Object options])	Highlighters are hidden by default. Calling this method is what makes them visible. The first, mandatory, parameter should be a NodeActor. NodeActors are what the WalkerActor return. It's easy to get a NodeActor for an existing DOM node. For example toolbox.walker.querySelector(toolbox.walker.rootNode, "css selector") resolves to a NodeFront (the client-side version of the NodeActor) which can be used as the first parameter. The second, optional, parameter depends on the type of highlighter being used.
hide()	Hides the highlighter.
finalize()	Destroys the highlighter.

Inserting content in the page

Highlighters use web technology themselves to display the required information on screen. For instance, the box-model highlighter uses SVG to draw the margin, border, padding and content regions over the highlighted node.

This means the highlighter content needs to be inserted in the page, but in a non-intrusive way. Indeed, the DevTools should never alter the page unless the alteration was done by the user (like changing the DOM using the inspector or a CSS rule via the style-editor for example). So simply appending the highlighter's markup in the content document is not an option.

Furthermore, highlighters not only need to work with Firefox Desktop, but they should work just as well on Firefox OS, Firefox for Android, and more generally anything that runs the Gecko rendering engine. Therefore appending the highlighter's markup to the browser chrome XUL structure isn't an option either.

To this end, DevTools highlighters make use of a (chrome-only) API:

 /**
  * Chrome document anonymous content management.
  * This is a Chrome-only API that allows inserting fixed positioned anonymous
  * content on top of the current page displayed in the document.
  * The supplied content is cloned and inserted into the document's CanvasFrame.
  * Note that this only works for HTML documents.
  */
 partial interface Document {
   /**
    * Deep-clones the provided element and inserts it into the CanvasFrame.
    * Returns an AnonymousContent instance that can be used to manipulate the
    * inserted element.
    */
   [ChromeOnly, NewObject, Throws]
   AnonymousContent insertAnonymousContent(Element aElement);
   
   /**
    * Removes the element inserted into the CanvasFrame given an AnonymousContent
    * instance.
    */
   [ChromeOnly, Throws]
   void removeAnonymousContent(AnonymousContent aContent);
 };

Using this API, it is possible for chrome-privileged JS to insert arbitrary DOM elements on top of the content page.

Consider the following simple example:

 let el = document.createElement("div");
 el.textContent = "My test element";
 let insertedEl = document.insertAnonymousContent(el);

In this example, the test DIV will be inserted in the page, and will be displayed on top of everything else, in a way that doesn't impact the current layout.

Note that the returned insertedEl object isn't a DOM node, its API is described further in this article.