130
edits
DevTools/Highlighter: Difference between revisions
Jump to navigation
Jump to search
Improved the content insertion doc and added doc for CanvasFrameAnonymousContentHelper
(Finalized the section about using the highlighter) |
(Improved the content insertion doc and added doc for CanvasFrameAnonymousContentHelper) |
||
| Line 80: | Line 80: | ||
|} | |} | ||
== Inserting content in the page == | == Creating new highlighters == | ||
Before digging into how one goes about adding a new type of highlighter to the DevTools, it is worth understanding how are highlighters displayed in the page. | |||
=== 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. | 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. | ||
| Line 115: | Line 119: | ||
Using this API, it is possible for chrome-privileged JS to insert arbitrary DOM elements on top of the content page. | Using this API, it is possible for chrome-privileged JS to insert arbitrary DOM elements on top of the content page. | ||
Technically, the DOM element is inserted into the <code>CanvasFrame</code> of the document. The <code>CanvasFrame</code> is part of the rendered frame tree and the DOM element is part of the native anonymous elements of the <code>CanvasFrame</code>. | |||
Consider the following simple example: | Consider the following simple example: | ||
| Line 124: | Line 130: | ||
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. | 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. | ||
=== The AnonymousContent API === | |||
In the previous example, the returned <code>insertedEl</code> object isn't a DOM node, and it certainly is not <code>el</code>. It is a new object, whose type is <code>AnonymousContent</code> ([http://mxr.mozilla.org/mozilla-central/source/dom/webidl/AnonymousContent.webidl?force=1 see the WebIDL here]). | |||
Because of the way content is inserted into the page, it isn't wanted to give consumers a direct reference to the inserted DOM node. This is why <code>document.insertAnonymousContent(el)</code> actually '''clones''' <code>el</code> and returns a new object whose API lets consumers make changes to the inserted element in a way that never gives back a reference to the inserted DOM node. | |||
=== CanvasFrameAnonymousContentHelper === | |||
In order to help with the API described in the previous section, the <code>CanvasFrameAnonymousContentHelper</code> class was introduced. | |||
Its goal is to provide a simple way for highlighters to insert their content into the page and modify it dynamically later. One of its goal is also to re-insert the highlighters' content on page navigation. Indeed, the frame tree is destroyed when the page is navigated away from since it represents the document element. | |||
Using this helper is quite simple: | |||
this.helper = new CanvasFrameAnonymousContentHelper(tabActor, this.buildMarkup.bind(this)); | |||
It only requires a <code>tabActor</code>, which highlighters get when they are instantiated, and a callback function that will be used to create and insert the content the first time the highlighter is shown, and every time there's a page navigation. | |||
The returned object provides the following API: | |||
== == | == == | ||
== The AnonymousContent API == | == The AnonymousContent API == | ||