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:

Box-model highlighter

But there can be a whide 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,
• etc.

== 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 onlly need to work with Firefox Desktop, but they should work just as well on FirefoxOS, Firefox for Android, and more generally anything that runs Gecko. 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.

== AnonymousContent API