mozilla

Revision 370875 of Appendix E: DOM Building and HTML Insertion

  • Revision slug: XUL/School_tutorial/DOM_Building_and_HTML_Insertion
  • Revision title: Appendix E: DOM Building and HTML Insertion
  • Revision id: 370875
  • Created:
  • Creator: diegocr
  • Is current revision? No
  • Comment

Revision Content

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

{{deprecated_header(15)}}

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;
   default:
       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 = {};
document.documentElement.appendChild(
    xmlToDOM(<hbox xmlns:html={HTML}>
            <html:div>
                <a href={href} target="_top" key="link">{text}</a>
            </html:div>
        </hhox>,
        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.

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));
                else
                    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,
                                       vals[1]);

        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);
            else
                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 = {};
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);

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";
 $("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) 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>\
    </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 {{ ifmethod("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]
                               .getService(Ci.nsIParserUtils);
        if ("parseFragment" in parser)
            return parser.parseFragment(html, allowStyle ? parser.SanitizerAllowStyle : 0,
                                        !!isXML, baseURI, doc.documentElement);
    }

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

Original Document Information

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

 

 

Revision Source

<p>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.</p>
<h2 id="Building_DOM_Trees">Building DOM Trees</h2>
<p>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.</p>
<h3 id="E4X_Templating">E4X Templating</h3>
<p>{{deprecated_header(15)}}</p>
<p>The following function can be used to generate DOM nodes from <a href="/en/E4X" title="en/E4X">E4X</a> XML objects. It has the advantage of appearing identical to ordinary HTML, but the disadvantage of being nearly exclusive to Firefox.</p>
<pre class="brush: js">
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 &amp;&amp; "@key" in xml)
           nodes[xml.@key] = domnode;
       return domnode;
   default:
       return null;
   }
}</pre>
<p>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.</p>
<pre class="brush: js">
default xml namespace = XUL;

var href = "http://www.google.com/";
var text = "Google";
var nodes = {};
document.documentElement.appendChild(
    xmlToDOM(&lt;hbox xmlns:html={HTML}&gt;
            &lt;html:div&gt;
                &lt;a href={href} target="_top" key="link"&gt;{text}&lt;/a&gt;
            &lt;/html:div&gt;
        &lt;/hhox&gt;,
        document, nodes);

    nodes.link.addEventListener("click", function (event) { alert(event.target.href); }, false);</pre>
<h3 id="JSON_Templating">JSON Templating</h3>
<p>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.</p>
<pre class="brush: js">
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));
                else
                    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,
                                       vals[1]);

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

            vals = namespace(key);
            if (typeof val == "function")
                elem.addEventListener(key.replace(/^on/, ""), val, false);
            else
                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);
}
</pre>
<p>In the above, the <code>namespaces</code> 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.</p>
<pre class="brush: js">
var href = "http://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);
</pre>
<h3 id="jQuery_Templating">jQuery Templating</h3>
<p>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 <code>.append()</code> and <code>.html()</code>. In most cases, <code>.text()</code> should be used instead of the latter. When using the <code>jQuery</code> constructor, only empty tags should be specified in order to avoid invoking the DOM parser.</p>
<pre class="brush: js">
var href = "http://www.google.com/";
var text = "Google";
 $("body").append(
    $("&lt;div&gt;", { class: "foo" })
        .append($("&lt;a&gt;", { href: href, text: text })
                    .click(function (event) { alert(event.target.href) }))
        .append($("&lt;span&gt;").text("Foo")));</pre>
<h3 id="innerHTML_with_HTML_Escaping">innerHTML with HTML Escaping</h3>
<p>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 <code>innerHTML</code> if any dynamic content in the value is escaped with the following function:</p>
<pre class="brush: js">
function escapeHTML(str) str.replace(/[&amp;"&lt;&gt;]/g, function (m) ({ "&amp;": "&amp;amp;", '"': "&amp;quot;", "&lt;": "&amp;lt;", "&gt;": "&amp;gt;" })[m]);</pre>
<p>Or slightly more verbose, but slightly more efficient:</p>
<pre class="brush: js">
function escapeHTML(str) str.replace(/[&amp;"&lt;&gt;]/g, function (m) escapeHTML.replacements[m]);
escapeHTML.replacements = { "&amp;": "&amp;amp;", '"': "&amp;quot;", "&lt;": "&amp;lt;", "&gt;": "&amp;gt;" };</pre>
<p>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.</p>
<pre class="brush: js">
var href = "http://www.google.com/";
var text = "Google";

document.getElementById("target-div").innerHTML = '&lt;div&gt;\
        &lt;a href="' + escapeHTML(href) '" target="_top"&gt;' + escapeHTML(text) + '&lt;/a&gt;\
    &lt;/div&gt;'
</pre>
<p>It needs to be stressed that this method <strong>should not be used in new code</strong> and is only a temporary measure to shore up legacy code bases.</p>
<h2 id="Safely_Generating_Event_Listeners_and_Scripts"><a id="listeners">Safely Generating Event Listeners and Scripts</a></h2>
<p>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 <code>'callback("' + str + '")'</code> appear anywhere in your add-on.</p>
<h3 id="Closures">Closures</h3>
<p>By far the best way to create dynamic event listeners is to use closures. The following two code fragments are roughly equivalent:</p>
<pre class="brush: js">
function clickify(elem, address) {
    elem.addEventListener("click", function (event) { openWindow(address) }, false);
}

function clickify(elem, address) {
    elem.onclick = function (event) { openWindow(address) };
}</pre>
<h3 id="Multiple_Attributes">Multiple Attributes</h3>
<p>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:</p>
<pre class="brush: js">
function clickify(elem, address) {
    elem.setAttribute("href", address);
    elem.setAttribute("onclick", "openWindow(this.getAttribute('href'))");
}</pre>
<h3 id="Escaping_Functions">Escaping Functions</h3>
<p>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 <code>uneval</code>, <a href="/en/JavaScript/Reference/Global_Objects/String/quote" title="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String/quote"><code>String.quote</code></a>, <a href="/en/JavaScript/Reference/Global_Objects/JSON/stringify" title="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/JSON/stringify"><code>JSON.stringify</code></a>, or <a href="/en/JavaScript/Reference/Global_Objects/Number" title="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Number">Number</a>. Generating scripts in this matter is deprecated and <strong>should be avoided wherever possible</strong>, but is relatively safe and sometimes acceptable.</p>
<pre class="brush: js">
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)] + ")";
}</pre>
<h2 id="Safely_Using_Remote_HTML">Safely Using Remote HTML</h2>
<p>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 {{ ifmethod("nsIParserUtils","parseFragment") }} method will convert a string to a document fragment while removing any scripts or other unsafe content in the process.</p>
<pre class="brush: js">
/**
 * 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 &lt;style&gt; 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]
                               .getService(Ci.nsIParserUtils);
        if ("parseFragment" in parser)
            return parser.parseFragment(html, allowStyle ? parser.SanitizerAllowStyle : 0,
                                        !!isXML, baseURI, doc.documentElement);
    }

    return Components.classes["@mozilla.org/feed-unescapehtml;1"]
                     .getService(Components.interfaces.nsIScriptableUnescapeHTML)
                     .parseFragment(html, !!isXML, baseURI, doc.documentElement);
}
</pre>
<p>The returned fragment may be appended to any element in the given document.</p>
<pre class="brush: js">
document.body.appendChild(parseHTML(document, xhr.responseText, true, xhr.channel.URI));
</pre>
<h2 id="See_Also">See Also</h2>
<ul>
  <li><a href="/En/Displaying_web_content_in_an_extension_without_security_issues" title="En/Displaying_web_content_in_an_extension_without_security_issues">Displaying web content in an extension without security issues</a></li>
  <li><a href="/en/How_to_create_a_DOM_tree" title="https://developer.mozilla.org/en/How_to_create_a_DOM_tree">How to create a DOM tree</a></li>
  <li>{{ domxref("Node.textContent") }}</li>
  <li>{{ domxref("Node.appendChild()") }}</li>
  <li>{{ domxref("element.setAttribute()") }}</li>
  <li><a href="/en/document.createElement">document.createElement()</a></li>
  <li><a href="/en/document.createTextNode">document.createTextNode()</a></li>
</ul>
<div class="originaldocinfo">
  <h2 id="Original_Document_Information" name="Original_Document_Information">Original Document Information</h2>
  <ul>
    <li>Author(s): Kris Maglione</li>
    <li>Last Updated Date: 2011-08-08</li>
  </ul>
</div>
<p>&nbsp;</p>
<div id="colortransformcanvas">
  &nbsp;</div>
Revert to this revision