We're looking for a user researcher to understand the needs of developers and designers. Is this you or someone you know? Check out the post: https://mzl.la/2IGzdXS

Appendix E: DOM Building and HTML Insertion Redirect 1

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

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.

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

    function tag(name, attr) {
        if (Array.isArray(name)) {
            var frag = doc.createDocumentFragment();
            Array.forEach(arguments, function (arg) {
                if (!Array.isArray(arg[0]))
                    frag.appendChild(tag.apply(null, arg));
                    arg.forEach(function (arg) {
                        frag.appendChild(tag.apply(null, arg));
            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]);

Or slightly more verbose, but slightly more efficient:

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

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

 * 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) {
    const PARSER_UTILS = "@mozilla.org/parserutils;1";

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

    return Components.classes["@mozilla.org/feed-unescapehtml;1"]
                     .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

Original Document Information

  • Author(s): Kris Maglione
  • Last Updated Date: 2011-08-08



Document Tags and Contributors

Last updated by: teoli,