Apéndice E: DOM e inserción HTML

This is an archived page. It's not actively maintained.

Support for extensions using XUL/XPCOM or the Add-on SDK was removed in Firefox 57, released November 2017. As there is no supported version of Firefox enabling these technologies, this page will be removed by December 2020.

Add-ons using the techniques described in this document are considered a legacy technology in Firefox. Don't use these techniques to develop new add-ons. Use WebExtensions instead. If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions.

Starting from Firefox 53, no new legacy add-ons will be accepted on addons.mozilla.org (AMO) for desktop Firefox and Firefox for Android.

Starting from Firefox 57, only extensions developed using WebExtensions APIs will be supported on Desktop Firefox and Firefox for Android.

Even before Firefox 57, changes coming up in the Firefox platform will break many legacy extensions. These changes include multiprocess Firefox (e10s), sandboxing, and multiple content processes. Legacy extensions that are affected by these changes should migrate to use WebExtensions APIs if they can. See the "Compatibility Milestones" document for more information.

A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.

Many add-ons need to dynamically generate DOM content, either XUL or HTML, from their scripts. For security reasons, and to prevent errors, care needs to be taken to avoid evaluating arbitrary text as HTML. Failure to do so can lead to execution or remote scripts, and in the worst cases to privilege escalation which can leave a user's PC open to remote attack.

Building DOM Trees

In most cases, DOM trees should be built exclusively with DOM creation methods. The following methods will all safely create a DOM tree without risk of remote execution.

E4X Templating

The following function can be used to generate DOM nodes from E4X XML objects. It has the advantage of appearing identical to ordinary HTML, but the disadvantage of being nearly exclusive to Firefox.

var HTML = Namespace("html", "http://www.w3.org/1999/xhtml");
var XUL = Namespace("xul", "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul");

default xml namespace = HTML;
function xmlToDOM(xml, doc, nodes) {
   if (xml.length() != 1) {
       let domnode = doc.createDocumentFragment();
       for each (let child in xml)
           domnode.appendChild(xmlToDOM(child, doc, nodes));
       return domnode;
   switch (xml.nodeKind()) {
   case "text":
       return doc.createTextNode(String(xml));
   case "element":
       let domnode = doc.createElementNS(xml.namespace(), xml.localName());
       for each (let attr in xml.@*::*)
           domnode.setAttributeNS(attr.namespace(), attr.localName(), String(attr));

       for each (let child in xml.*::*)
           domnode.appendChild(xmlToDOM(child, doc, nodes));
       if (nodes && "@key" in xml)
           nodes[xml.@key] = domnode;
       return domnode;
       return null;

When passed an XML literal and a document, it returns the DOM tree corresponding to the XML for that document. If passed a third argument, the DOM node created for any element with a "key" attribute, is stored in a property of the given object named for the "key" attribute's value.

default xml namespace = XUL;

var href = "http://www.google.com/";
var text = "Google";
var nodes = {};
    xmlToDOM(<hbox xmlns:html={HTML}>
                <a href={href} target="_top" key="link">{text}</a>
        document, nodes);

    nodes.link.addEventListener("click", function (event) { alert(event.target.href); }, false);

JSON Templating

For code which needs to be cross-browser compatible, a similar templating system can be used, based on JSON objects rather than E4X. It also has the advantage of being slightly more concise than the E4X variant, though no easier to read.

var namespaces = {
    html: "http://www.w3.org/1999/xhtml",
    xul: "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"

jsonToDOM.defaultNamespace = namespaces.html;
function jsonToDOM(xml, doc, nodes) {
    function namespace(name) {
       var m = /^(?:(.*):)?(.*)$/.exec(name);
       return [namespaces[m[1]], m[2]];

   function tag(name, attr) {
       if (isArray(name)) {
           var frag = doc.createDocumentFragment();
           Array.forEach(arguments, function (arg) {
               if (!isArray(arg[0]))
                   frag.appendChild(tag.apply(null, arg));
                   arg.forEach(function (arg) {
                       frag.appendChild(tag.apply(null, name[i]));
           return frag;

       var args = Array.slice(arguments, 2);
       var vals = namespace(name);
       var elem = doc.createElementNS(vals[0] || jsonToDOM.defaultNamespace,

       for (var key in attr) {
           var val = attr[key];
           if (nodes && key == "key")
               nodes[val] = elem;

           vals = namespace(key);
           if (typeof val == "function")
               elem.addEventListener(key.replace(/^on/, ""), val, false);
               elem.setAttributeNS(vals[0] || "", vals[1], val);
       args.forEach(function(e) {
           elem.appendChild(typeof e == "object" ? tag.apply(null, e) :
                            e instanceof Node    ? e : doc.createTextNode(e));
       return elem;
   return tag.apply(null, xml);

In the above, the namespaces object defines the namespace prefixes which can be used in the given DOM tree. Event listeners can be defined on the given nodes by passing functions rather than strings to on* attributes.

var href = "http://www.google.com/";
var text = "Google";
var nodes = {};
    jsonToDOM(["xul:hbox", {},
        ["div", {},
            ["a", { href: href, key: "link",
                    onclick: function (event) { alert(event.target.href); } },
            ["span", { class: "stuff" },
        document, nodes));


jQuery Templating

For extensions which already use jQuery, it is possible to use its builtin DOM building functions for templating, though care must be taken when passing non-static strings to methods such as .append() and .html(). In most cases, .text() should be used instead of the latter. When using the jQuery constructor, only empty tags should be specified in order to avoid invoking the DOM parser.

var href = "http://www.google.com/";
var text = "Google";
    $("<div>", { class: "foo" })
        .append($("<a>", { href: href, text: text })
                    .click(function (event) { alert(event.target.href) }))

innerHTML with HTML Escaping

This method is a last resort which should be used only as a temporary measure in established code bases. It is safe, though inefficient, to assign dynamic values to innerHTML if any dynamic content in the value is escaped with the following function:

function escapeHTML(str) str.replace(/[&"<>]/g, function (m) "&" + ({ "&": "amp", '"': "quot", "<": "lt", ">": "gt" })[m] + ";");

Note that quotation marks must be escaped in order to prevent fragments escaping attribute values, and that single quotes may not be used to quote attribute values in the fragment.

var href = "http://www.google.com/";
var text = "Google";

document.getElementById("target-div").innerHTML = '<div>\
        <a href="' + escapeHTML(href) '" target="_top">' + escapeHTML(text) + '</a>\

It needs to be stressed that this method should not be used in new code and is only a temporary measure to shore up legacy code bases.

Safely Generating Event Listeners and Scripts

It is occasionally necessary to generate event listeners and script fragments from dynamic content. Great care must be taken in these situations. Under no circumstances should code resembling 'callback("' + str + '")' appear anywhere in your add-on.


By far the best way to create dynamic event listeners is to use closures. The following two code fragments are roughly equivalent:

function clickify(elem, address) {
    elem.addEventListener("click", function (event) { openWindow(address) }, false);

function clickify(elem, address) {
    elem.onclick = function (event) { openWindow(address) };

Multiple Attributes

Sometimes there is a need for event listeners to appear as attributes in the DOM. In these cases, multiple attributes should be used, one for each variable:

function clickify(elem, address) {
    elem.setAttribute("href", address);
    elem.setAttribute("onclick", "openWindow(this.getAttribute('href'))");

Escaping Functions

When the code fragment in question is not an event handler attribute and there is no feasible way to pass the data through other means, they must be escaped with functions such as uneval, String.quote, JSON.stringify, or Number. Generating scripts in this matter is deprecated and should be avoided wherever possible, but is relatively safe and sometimes acceptable.

function createScript(href, otherStuff) {
    var script = function (href, otherStuff) {
        for (var someStuff in otherStuff)

    return script.toSource() + "(" + [String.quote(href), uneval(otherStuff)] + ")";

Safely Using Remote HTML

In the above cases, we're working with text content that needs to appear in generated DOM. There are cases, however, where we need to safely display formatted HTML sent by a remote server. Fortunately, there is a safe and simple way to do this. The nsIScriptableUnescapeHTML.parseFragment() method will convert a string to a document fragment while removing any scripts or other unsafe content in the process.

function ParseHTML(doc, html) {
    return Components.classes["@mozilla.org/feed-unescapehtml;1"]
                     .parseFragment(html, false, null, doc.documentElement);

The returned fragment may be appended to any element in the given document.

document.body.appendChild(ParseHTML(document, xhr.responseText, xhr.channel.name);