Appendix E: DOM Building and Insertion (HTML & XUL)

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.

JSON Templating

jsonToDOM.namespaces = {
    html: "https://www.w3.org/1999/xhtml",
    xul: "https://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
};
jsonToDOM.defaultNamespace = jsonToDOM.namespaces.html;
function jsonToDOM(jsonTemplate, doc, nodes) {
    function namespace(name) {
        var reElemNameParts = /^(?:(.*):)?(.*)$/.exec(name);
        return { namespace: jsonToDOM.namespaces[reElemNameParts[1]], shortName: reElemNameParts[2] };
    }

    // Note that 'elemNameOrArray' is: either the full element name (eg. [html:]div) or an array of elements in JSON notation
    function tag(elemNameOrArray, elemAttr) {
        // Array of elements?  Parse each one...
        if (Array.isArray(elemNameOrArray)) {
            var frag = doc.createDocumentFragment();
            Array.forEach(arguments, function(thisElem) {
                frag.appendChild(tag.apply(null, thisElem));
            });
            return frag;
        }

        // Single element? Parse element namespace prefix (if none exists, default to defaultNamespace), and create element
        var elemNs = namespace(elemNameOrArray);
        var elem = doc.createElementNS(elemNs.namespace || jsonToDOM.defaultNamespace, elemNs.shortName);

        // Set element's attributes and/or callback functions (eg. onclick)
        for (var key in elemAttr) {
            var val = elemAttr[key];
            if (nodes && key == "key") {
                nodes[val] = elem;
                continue;
            }

            var attrNs = namespace(key);
            if (typeof val == "function") {
                // Special case for function attributes; don't just add them as 'on...' attributes, but as events, using addEventListener
                elem.addEventListener(key.replace(/^on/, ""), val, false);
            }
            else {
                // Note that the default namespace for XML attributes is, and should be, blank (ie. they're not in any namespace)
                elem.setAttributeNS(attrNs.namespace || "", attrNs.shortName, val);
            }
        }

        // Create and append this element's children
        var childElems = Array.slice(arguments, 2);
        childElems.forEach(function(childElem) {
            if (childElem != null) {
                elem.appendChild(
                    childElem instanceof doc.defaultView.Node ? childElem :
                        Array.isArray(childElem) ? tag.apply(null, childElem) :
                            doc.createTextNode(childElem));
            }
        });

        return elem;
    }

    return tag.apply(null, jsonTemplate);
}

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 = "https://www.google.com/";
var text = "Google";
var nodes = {};
document.documentElement.appendChild(
    jsonToDOM(["xul:hbox", {},
        ["div", {},
            ["a", { href: href, key: "link",
                    onclick: function (event) { alert(event.target.href); } },
                text],
            ["span", { class: "stuff" },
                "stuff"]]],
        document, nodes));

alert(nodes.link);

function addEntryToPopup(menuPopup, doc, chromeWindow) {
    var newItem = doc.createElement("menuitem");
    newItem.setAttribute("value", "testValue");
    newItem.setAttribute("label", "Another popup menu item");
    menuPopup.appendChild(newItem);
};

var jsonTemplateBtn =
    ["xul:toolbarbutton",
        {
            id: "myTestButton",
            class: "toolbarbutton-1",
            type: "menu",
            label: "Test button label",
            tooltiptext: "Test button tooltip",
            removable: true,
            key: "myTestButton123"
        },
        [ "menupopup",
            {
                onpopupshowing: function(event) { addEntryToPopup(this, document, window); }
            },
            null
        ]
    ];
var capturedNodes = {};

var toolbox = doc.getElementById("navigator-toolbox");
var palette = toolbox.palette;
var domFragment = jsonToDOM(jsonTemplateBtn, document, capturedNodes);
palette.appendChild(domFragment);

alert("capturedNodes contains any created nodes that have optionally been captured (for later convenient JavaScript access) by giving them a 'key' attribute; for example: " + capturedNodes.myTestButton123);

Another Example

This here is another example of using jsonToDOM but in the HTML scope, a complex form is created with ease. The demo of this is seen at jsfiddle :: jsonToDOM Example

var json =
['html:div', {style:'background-color:springgreen'},
    ['html:form', {id:'myFirstForm'},
            ['html:input', {type:'text', value:'my field'}],
            ['html:button', {id:'myBtn'}, 'Button Text Content']
    ],
    ['html:form', {id:'mySecondForm'},
            ['html:input', {type:'text', value:'my field for second form'}],
            ['html:div', {},
                'Sub Div with textcontent and siblings',
                ['html:br', {}],
                ['html:input', {type:'checkbox', id:'mycheck'}],
                ['html:label', {for:'mycheck'},
                    'here is text of label, click this text will check the box'
                ]
            ]
    ]
];

document.body.appendChild(jsonToDOM(json, document, {}));

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 = "https://www.google.com/";
var text = "Google";
 $("body").append(
    $("<div>", { class: "foo" })
        .append($("<a>", { href: href, text: text })
                    .click(function (event) { alert(event.target.href) }))
        .append($("<span>").text("Foo")));

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) { return str.replace(/[&"'<>]/g, (m) => ({ "&": "&amp;", '"': "&quot;", "'": "&#39;", "<": "&lt;", ">": "&gt;" })[m]); }

Or slightly more verbose, but slightly more efficient:

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

Note that quotation marks must be escaped in order to prevent fragments escaping attribute values.

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

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

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.

Closures

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) {
        doStuffWith(href);
        doOtherStuff();
        for (var someStuff in otherStuff)
            doSomeMoreStuffWith(someStuff);
    }

    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 nsIParserUtils.parseFragment() method will convert a string to a document fragment while removing any scripts or other unsafe content in the process.

let { Cc, Ci } = require("chrome");
/**
 * Safely parse an HTML fragment, removing any executable
 * JavaScript, and return a document fragment.
 *
 * @param {Document} doc The document in which to create the
 *     returned DOM tree.
 * @param {string} html The HTML fragment to parse.
 * @param {boolean} allowStyle If true, allow <style> nodes and
 *     style attributes in the parsed fragment. Gecko 14+ only.
 * @param {nsIURI} baseURI The base URI relative to which resource
 *     URLs should be processed. Note that this will not work for
 *     XML fragments.
 * @param {boolean} isXML If true, parse the fragment as XML.
 */
function parseHTML(doc, html, allowStyle, baseURI, isXML) {
    let PARSER_UTILS = "@mozilla.org/parserutils;1";

    // User the newer nsIParserUtils on versions that support it.
    if (PARSER_UTILS in Cc) {
        let parser = Cc[PARSER_UTILS]
                               .getService(Ci.nsIParserUtils);
        if ("parseFragment" in parser)
            return parser.parseFragment(html, allowStyle ? parser.SanitizerAllowStyle : 0,
                                        !!isXML, baseURI, doc.documentElement);
    }

    return Cc["@mozilla.org/feed-unescapehtml;1"]
                     .getService(Ci.nsIScriptableUnescapeHTML)
                     .parseFragment(html, !!isXML, baseURI, doc.documentElement);
}

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

document.body.appendChild(parseHTML(document, xhr.responseText, true, xhr.channel.URI));

See Also

• Displaying web content in an extension without security issues
• How to create a DOM tree
• Node.textContent
• Node.appendChild()
• element.setAttribute()
• document.createElement()
• document.createTextNode()