Discussion: Templates that Don't Destroy Element References

[Lonniebiz]

In the same manner that tagged template literals allow the embedding of interpolated JavaScript expressions, I think it would be awesome if HTML <template> tags (or some new tag type) allowed ${elementReferenceName} expressions also. Then, instead of cloning a template, you could just instantiate it in the same manner you would an object from a class (without losing your element references), and when you do this the interpolated values could be based on the original context from where the instantiation occurs (or through .bind to specify an alternative context), kind of like arrow function scoping but with bindablity.

Also, I think if an interpolation's output is anything other than an element, the template-instantiation should covert that output to a static string that cannot be modified. There's no need to update the template if you can instead update the dynamic elements that were place into it. Cloning destroys your element references. Template instantiation should keep those element references! This way, at the custom class level, you'll always be able to modify the vary same elements you created before injecting it into the template.

I need something like the <template> tag that I can stick inside my custom class's constructors, where each time I instantiate it, it will contain the same referenced element I created in that constructor. Cloning is a pain; you clone it and then you have modify it before it goes out so that you can maintain element references. Cloning is fine for some things, but not ideal inside a class constructor.

If we had a <template> tag like this; it would be all I'd ever need.

[bahrus]

There is a proposal along the lines of what you are suggesting, I think.

[Lonniebiz]

Besides editing it. How can I get my comment above in front of the eyes of the people making that proposal?

[rniwa]

If you'd like, we can converse over email or video conf about this. Shoot me an email me at webkit.org or apple.com (username is same as my Github username).

[Lonniebiz]

Yes, let's discuss. I sent an email @webkit.org (same handle as here).

[Lonniebiz]

This is how I'd like the process of creating a web component to be.

1. Manually create the dynamic elements that will change in the web component. Pretend that every thing below is happening in the constructor of a web component:

this.div = document.createElement("div");
div.textContent = "Click Here to See an Alert";
div.addEventListener('click', (event)=>{alert(`You've click a div that contained this text: ${this.div.textContent}`)});

2. Use a template literal to create a string where all dynamic parts are combined with element-interpolations (${expressionThatReturnsAnElement}):

let soonToBeDOM = `<h1>See Below</h1>${div}<p>Click the sentence above to see alert.</p>`;

3. Now, feed this template literal to an HTML template:

let template =  document.createElement("template");
let dom = template.buildFromLiteral(soonToBeDOM);

At this point pretend we've created actual DOM that contains the static and dynamic parts. And most importantly, the reference to this.div remains accessible throughout the life cycle of our web component instance. Any update method would be able to modify this.div (fast as possible) with a direct reference and the event listener we created at the beginning continues to work.

The template tag, never needs to be re-rendered. If you need to update something. You modify the element directly (by reference).

This how I'd like it to work. hyperHTML and lit-html accomplish this same type of thing, but if that .buildFromLiteral method above worked natively, it would be even faster than they've accomplished. Because, in order for them to do it, they are having to replace interpolations with comment nodes before cloning the HTML template. Then, after cloning the template, they have to retrieve references for all those comment nodes, something like this:

const getCommentNodes = function(element)
{
	let treeWalker = document.createTreeWalker(element, NodeFilter.SHOW_COMMENT);
	let commentNodes = [];
	while(treeWalker.nextNode()) {commentNodes.push(treeWalker.currentNode);}
	return commentNodes;
};

Lastly, they are having to replace each comment node with the actual element created within the web-component's constructor.

And they are not just doing element-interpolations either. They support strings, fragments, promises and other interpolations/expression output types.

So if you could generate an HTML <template> by feeding it a template literal containing expressions/interpoations, AND if that template element natively knew how to handle ${expressionsThatOutputElements}, it would just simply be awesome....

The only thing I care about is element-interpolations. I'll separate static from dynamic myself. As long as I can reference the dynamic parts via element-reference, I've got all I'll ever need.

[rniwa]

@justinfagnani

[rniwa]

Thanks. I think what we proposed would achieve something very close to what you want / are proposing. Fundamentally, there are two important pieces to the template API we’ve been discussing.

1. TemplatePart - It’s an object in DOM tree which keeps track of positions and be able to insert & replace any number of nodes at that location. This is basically a replacement for Comment node libraries like lit-html uses, and lets you very easily update the instance of a template.
2. Template parser - This is the thing that finds instances of {{~}} and replaces it with TemplatePart.

Let's say we have the HTML like this:

<template id="myTemplate">
<h1>See Below</h1>{{content}}<p>Click the sentence above to see alert.</p>
</template>

Then we can do something like this (the exact shape & naming of API is not yet settled but so take it with a grain of salt; e.g. which properties exist where, etc... can change):

const div = document.createElement("div");
div.textContent = "Click Here to See an Alert";
div.addEventListener('click', (event)=>{alert(`You click a div that contained this text: ${this.div.textContent}`)});
const instance = myTemplate.createInstance({content: div});

Here, createInstance uses the builtin template parser to find all instances of {{~}}, and creates an instance of TemplatePart for each. Then it assigned the "value" based on its name. The mapping / assignment behavior is completely customizable by defining your own template processor but that's what the default behavior would be.

Once you created an instance, you can insert that context into anywhere in the DOM:

document.body.appendChild(instance.content);

Obviously, you can access & mutate div anyway you want:

div.innerHTML = '<b>Click Here to See an Alert</b>';

In addition, the TemplatePart object which has been created for this instance can be updated. e.g.

const b = document.createElement('b');
b.textContent = 'Open an alert';
instance.parts['content'].replace(b);

[Lonniebiz]

What I'm proposing is more fundamental (and more efficient) than Template Instantiation, but not mutually exclusive to Template Instantiation. Here's how the two would complement each other. First I'll discuss what I'm proposing and later I'll tie that into the Template Instantiation proposal.

Template Literals already know the context from which to determine the values of the ${interpolations/expressions} they contain. They also already inherently know which portions of the string are "parts".

Template Literals, without the help of any type of HTML template element, already contain everything that needs to be known to generate DOM. Therefore, I think it would be ideal for Browsers to add 2 prototype method to all strings. One called toDOM() and the other called toTemplate(). Here's how this would work.

toDOM()

If you want to create live Dom (that's ready for the appendChild method) you use the toDOM() method:

// Again, pretend this is happening in a web component's constructor
this.btn = document.createElement("button");
btn.textContent = "Click Here to See an Alert";
btn.addEventListener('click', (event)=>
{
	alert(`You've clicked a button that contains this text: ${this.btn.textContent}.`)
});

let soonToBeDOM = 
`<h1>See Below</h1>${this.btn}<p>Click the sentence above to see alert.</p>`;

document.body.appendChild(soonToBeDOM.toDOM()); 
//button says: Click Here to See an Alert

setTimeout(()=>
{
	this.btn.textContent = "Nevermind";}, 5000);
	// this.btn says "Nevermind" after 5 seconds.
}

Notice that the this.btn element reference, created at the beginning of the constructor, survived the template literal all the way to DOM, and so did its click eventListener; if you click this.btn it will still fire. this.btn remains accessible to the web component for efficient changes throughout the entire life cycle of the web component.

Above is what I'd primarily use, because if I already have a direct object reference to the dynamic elements that change (which what I'm proposing would give you), there is no need for template updating. Therefore, there's no need for an intermediary template element and the added change-evaluation processing it brings with it for each interpolation each time the template is updated. An event fires, and you change only what needs to change, without ever even evaluating any of the interpolations that didn't change! This is as efficient as it gets.

toTemplate()

Here's where your proposal comes into the picture.
The toTemplate() does the same thing that the toDOM() method does, except it returns an inert html <template> element where all interpolations/expressions have been replaced with unnamed-TemplateParts. Later when you call the htmlTemplate.createInstance(['You','Pass','an','array','of','replacements']);

If you want each template part to have a name, you can pass names in during the toTemplate() method:
templateLiteral.toTemplate('array','of','named','parts');

Then, later when you call htmlTemplate.createInstance(), you pass in an object literal instead of an array if you originally gave the parts a name during .toTemplate().

And also, the examples you gave, where the template element was created in HTML, this will be fine too.

Summary

These two methods are fundamentally different ways of updating the dynamic aspects of a web component. The first method only gets called once and stuff that doesn't change doesn't even get evaluated (an event tells you exactly what changed and at most you evaluation only the one thing the event said changed). The Template Instantiation method has to evaluation each part on each update, looking for everything that might have changed. By handling your updates at the more fundamental level, the events themselves inherently tell you exactly what changed. Evaluating things that didn't change is unnecessary, but hyperHTML and lit-html do this for every interpolation on every template update. You don't have to compare anything to see what changed, the event inherently tells you what changed and you can go update that alone.

What I'm proposing is fundamental, but simple. templateLiteral.toDOM() is like a fancy innerHTML that understands when a ${JavaScriptExpression} is an element. This is all the "templating" I'll ever need.

[matthewp]

This seems a bit weird to me. The interpolation of:

`<h1>See Below</h1>${this.btn}<p>Click the sentence above to see alert.</p>`

produces:

"<h1>See Below</h1>[object HTMLButtonElement]<p>Click the sentence above to see alert.</p>"

You want the thing the literal produces to not be a string. To do that you need a tagged template literal like lit-html does. Such a function could work with template instantiation to produce what you want.

[Lonniebiz]

@matthewp : Yes, you're right, that's what string alone produces, and that's what the .toDom() method would handle. It ultimately converts that [object HTMLButtonElement] you're seeing (along with everything else in the string) to a DOM element. Kind of like innerHTML converts a string to DOM, but with the additional feature of being able to convert ${variableOfHandCreatedElementNode} to that vary element created and referenced at the beginning.

I'm saying that, when javascript is running in a web browser. There could be a prototype method called toDOM() on string (for all strings, including template literal strings).

However, if the string is a template literal, the method should be smart enough to interpret the ${elementNode} expression just like what is accomplished using tagged template literals, before producing the DOM.

My basic need is the ability to just mix a string of HTML with my own hand-crafted elementNode objects. The toDOM() method would produce the DOM I need very easily with nothing more. The events on my web components tell me exactly what changed without having to evaluate every other interpolation. I would never want to do a string lookup on a clone to replace a node. Each dynamic thing in my web components can be directly accessed via this.elementName and nothing is faster than that.

What I'm saying is not better than Template Instantiation. It just seems like a more fundamental thing that should precede Template Instantiation. After I get the DOM, you can garbage collect any template that may have been needed to give it to me.

I agree that the end result can be accomplished by lit-html, hyperHTML, and the Template Instantiation proposal. I look forward to seeing what is ultimately the standard on these concepts.

[matthewp]

For that to work the string would need to keep a reference to btn so that if toDOM() is ever called it can interpolate the actual element. But strings are value types. So they can't keep state.

[Lonniebiz]

Well, then I'd expect .toDOM() to throw an error if this.btn is not accessible from within the scope where .toDOM() is called. I'm fine with that; I won't need that original template literal at all after I have the DOM.

When you pass a template literal into a tag function, the tag function receives an array of static strings and an argument of each expression result. Couldn't a method on a template literal receive these same parameters automatically? Does it have to become a literal string value during the dot of .toDom()?

[matthewp]

Sounds like to make this method work you're going to have to make a lot of changes to JavaScript. Is it really that important to you that the method be on the string prototype? Why not just have a method toDOM on the window object (or somewhere else)?

[justinfagnani]

Maybe I'm missing something here, but what's wrong with a template tag? It cal already do all the things asked for here and makes it clear to the author that some special is going on compared to plain strings.

[rniwa]

Template Literals, without the help of any type of HTML template element, already contain everything that needs to be known to generate DOM. Therefore, I think it would be ideal for Browsers to add 2 prototype method to all strings. One called toDOM() and the other called toTemplate(). Here's how this would work.

...

Template Literals already know the context from which to determine the values of the ${interpolations/expressions} they contain. They also already inherently know which portions of the string are "parts".

There is a difference between the template literal and the string it generates. "~" is a template literal but the runtime semantics of a template literal is to generate a regular string. So once the template literal is evaluated (which happens once), then the generated string is no different from any other string and doesn't retain any information about the context or where the substations occurred.

This is precisely why our proposal uses {{~}} as opposed to ${~} so that we can retain these contexts beyond when the template is instantiated.

An alternative approach is to use tagged template literal like lit-html and hyperHTML. One big difference between a regular template literal and a tagged template literals is that the latter can return a non-string object.

Well, then I'd expect .toDOM() to throw an error if this.btn is not accessible from within the scope where .toDOM() is called. I'm fine with that; I won't need that original template literal at all after I have the DOM.

That's going to be an extremely exotic behavior because this .toDOM() function would be looking up things in its caller's scope. Since literally nothing else in the platform behaves like this, I don't think we should do this.

Template Literals, without the help of any type of HTML template element, already contain everything that needs to be known to generate DOM. Therefore, I think it would be ideal for Browsers to add 2 prototype method to all strings. One called toDOM() and the other called toTemplate(). Here's how this would work.

That would be a massive layering violation. Because ECMAScript is used in non-browser environments without DOM like node.js these days, adding any sort of DOM related API directly onto String would be a bad idea.

Having said that, I'm amendable to the idea that there probably is a valid use case for creating a template instance directly from a string. For example, I could imagine an alternative approach to instantiating a TemplateInstance perhaps via a constructor as in:

<template id="boldTemplate"><b>{{text}}</b></template>
<script>
const content = {text: 'hello, world'};
const instance1 = new TemplateInstance('<b>{{text}}</b>', content);
const instance2 = new TemplateInstance(boldTemplate, content);
</script>

where instance1 and instance2 are semantically equivalent template instances.

Alternatively, using tagged template literal, we could introduce something like htmlTemplate tag built into the browser which creates a HTMLTemplateElement or some kind of a DocumentFragment variant which knows it's a template fragment as in:

<template id="template3"><b>{{text}}</b></template>
<script>
const content = {text: 'hello, world'};
const template4 = htmlTemplate`<b>{{text}}</b>`;
const instance3 = template3.createInstance(content);
const instance4 = template4.createInstance(content);
</script>

Again, instance3 and instance4 are semantically identical. Now, because htmlTemplate is a tagged template literal, you can then insert a random DOM node as in:

const br = document.createElement('br');
const template5 = htmlTemplate`<b>{{text}}</b>${br}`;
const instance5 = template5.createInstance({text: "hello"});

Then instance5 would have the HTML fragment of <b>hello</b><br> as desired.

Note that instance5 would contain a different br element than the one we created for the template since each instance of a template must have its own br element. If, for example, you wanted to create a br in each template instance yourself, you'd do this instead:

const template5 = htmlTemplate`<b>{{text}}</b>{{suffix}}`;
const br = document.createElement('br');
const instance5 = template5.createInstance({text: "hello", suffix: br});

This is the closest thing I can come up with to what you're proposing without all the issues I listed above.