Proposal to improve the DOM creation api

[straker]

I'm sorry if this topic has been discussed already, I tried to do due diligence but couldn't find a similar proposal on the forums or the html or dom github repos.

The DOM creation api is a bit cumbersome to work with. To create a single element with several attributes requires several lines of code that repeat the same thing. The DOM selection api has received needed features that allow developers to do most DOM manipulation without needing a library. However, the DOM creation api still leaves something to be desired which sways developers from using it.

There are several use cases where the api is cumbersome to use. I have compiled a gist of just a few of them. It shows several use cases where the current api requires an awkward solution, and demonstrates a few common hacks of working around the native api to get a more manageable result. It also provides several examples of how popular libraries handle the same use case, usually in a simpler manner.

I would like to propose that the DOM creation api be improved so that developers have a cleaner interface into DOM creation and no longer need libraries to do it.

[annevk]

There has been discussion here: https://lists.w3.org/Archives/Public/www-dom/2011OctDec/thread.html#msg20. There was also http://www.hixie.ch/specs/e4h/strawman though TC39 didn't really like it. There is https://github.com/domenic/element-constructors by @domenic which should be finished at some point.

I don't think libraries have really converged on something here either, other than innerHTML-like approaches (which would suggest the E4H approach, perhaps amended to use template strings).

Also note that the libraries that use object-like notation often confuse content attributes and IDL attributes (aka JavaScript properties), which makes this rather tricky.

[straker]

Thanks for those resources, they were very enlightening.

From those discussions, it seems that template strings (or quasi-literal templates from the public archives) seem to be where the discussions keep coming back to, and seem to have generated the most consensus. With ES2015 template strings appearing to fulfill the role of the quasi-literal template proposal, I'm guessing the discussion should be focused on how to use the template string on the parent node?

Domenic's element constructors sounds a bit like Dart's solution to create a new constructor for elements (Dart went a bit farther and made one for each element). It looks like he uses the object-like notation to define namespaces or attribute declarations, so would it suffer from the same problem of confusing content attributes and IDL attributes?

[annevk]

Template strings seem like a way forward, though making them work with the HTML parser seems tricky. I think that is why nobody has tried thus far. Element constructors might indeed have that same problem, though they are also solving a more fundamental problem, that these classes don't have constructors. Which I think is why we want them either way, even if they didn't have convenient syntax for attributes and such.

[straker]

Ok. I'll go play with how browsers interpret different template strings and the HTML parser and see where it doesn't behave as expected. I'll post my findings here and focus on HTML parsing of template strings. Once a consensus on how to handle HTML parsing of template strings has been reached, the discussion could then turn into how to implement a convenient syntax for using the template string on the parent node.

Do you know of any more resources to discussions on template strings and the HTML parser?

[annevk]

Searching around I found https://lists.w3.org/Archives/Public/public-script-coord/2013JanMar/thread.html#msg263 and https://lists.w3.org/Archives/Public/public-script-coord/2013JanMar/thread.html#msg297.

[straker]

It seems that the discussion around E4H and template strings is more complicated than I would like this proposal to address. In the end, both template strings and E4H rely on the already existent DOM apis of appendChild or innerHTML to work with the DOM and don't introduce any new ones. https://lists.w3.org/Archives/Public/www-dom/2011OctDec/thread.html#msg20 eventually wound up going towards template strings, but it looked like they were proposing a new browser implemented function called html that would convert a string using the HTML parser (which reverts back to the E4H and template string debate).

With that in mind, I would like to propose adding new DOM apis that make these use cases much cleaner and easier to carry out:

1. creating a single node with attributes
   • if this could also handle the use case of creating a single node and it's children in a single step, that'd be great
2. creating a series of sibling nodes to be appended to a parent

These apis could then be used by either E4H or template strings, which ever one wins out in the end. If this new api is the html function, it shouldn't go through the HTML parser if it'll have problems such as https://lists.w3.org/Archives/Public/www-dom/2011OctDec/0170.html was describing. Instead, it should just accept the string it's given and create a tr with it's children, regardless if the node doesn't have context.

(a very simple approach that mimics the behavior would be)

function html(str) {
  var match = str.match(/<([^>]*)>/);
  var rootStr = match[1].trim().split(/\s/);
  var tagName = rootStr[0];
  var root = document.createElement(tagName);

  // attributes
  for (var i = 1; i < rootStr.length; i++) {
    var attr = rootStr[i];
    var name = attr.substring(0, attr.indexOf('='));
    var value = attr.match(/=['"]?([^'"]*)/)[1];

    root.setAttribute(name, value);
  }

  // children
  root.innerHTML = str.replace(match[0], '');  // kinda hakcy as it will ignore the orphaned closing tag

  return root;
}

console.log(html(`<tr class="foo" data-config=bar>
  <td class="hello">
    <span class="foo">bar</span>
  </td>
</tr>`));
console.log(html(`<tr>`));

[straker]

So I stumbled upon tagged template strings, which makes it seem that template strings and E4H can live in harmony. It would seem that you could remove (deprecate, etc.) the innerHTML function that takes a string and instead strictly use an HTML tagged function. The function can now understand the insertion points of the template string and can do E4H style processing to return safe DOM. This tagged function could also be used to just generate dom by itself.

This would be the new API to creating DOM that would satisfy my uses cases.

var text = "foo";

// `html` is the tagged template function that runs E4H

// create a single node with attributes
document.body.appendChild( html`<div class="bar">${text}</div>` );

// create a series of sibling nodes
var element = html`<div>${text}</div><div>bar</div>`;

[annevk]

Yeah, I think that kind of API would be ideal. @freddyb, any sanitizing library should look like the above ^^. Making this work with the HTML parser is a lot of work unfortunately.

[straker]

I thought one of the benefits of E4H was that you didn't have to go through the HTML parser. Either way, I would be happy to help get something like this working. What can I do to help?

[annevk]

That is true, E4H had a much simpler grammar. I don't know if folks would find that acceptable though. They probably expect similar parsing rules to <template> so you can write <img> as <img> and not <img/>, omit </td>, etc.

I don't know how familiar you are with the HTML parser, but figuring out what adjustments would need to be made to make html...`` work would be a good first step. Coupled perhaps with a basic algorithm for that template string function.

[domenic]

Personally I think the best first step is to produce a library with the desired semantics and have it get reasonable adoption, before we consider standardizing it. It's still early days for template strings and to me it doesn't make sense to talk about standardizing a template string tag yet.

[annevk]

Yeah, maybe. At some point we need to make sanitizing easier and add it to browsers. That will require a similar API of sorts. And also, this is hugely complicated to get right. @straker buliding a prototype on top of https://github.com/inikulin/parse5 (or similar library) might be a good first step here.

[straker]

Sounds good, I'll get to work getting a prototype using a tagged template function built on top of a parsing library. I'll also see if I can incorporate some of the E4H ideals into it just as a proof of concept.

[domenic]

I'm not sure why you need a parsing library exactly? Can't you just use

document.createElement("template");
template.innerHTML = passedInStringAfterSubstitutions;
return template.contents;

Maybe the problem is safely generated passedInStringAfterSubstitutions. but maybe it's not; just do HTML escaping and then concatenation. See e.g. https://github.com/domenic/count-to-6/blob/master/lib/exercises/tagged_template_strings/solution/solution.js

[straker]

If you didn't care that you always escaped the substituted DOM that would work, but what happens when I trust the substitution (e.g. I created it) and don't want to escape it so it will create DOM instead of string escaped text?

I'm guessing that this contributes to what makes this problem hugely complicated to get right.