Supply html tag function for generating template in modules

[kevinpschaaf]

Description

Currently static get template() can return an HTMLTemplateElement or a string which is internally parsed into a template. When moving to modules in Polymer 3, all templates from dom-modules are automatically moved into strings returned from the static template getter by modulizer, and all newly authored elements would be expected to just return strings. This will be problematic for any Polymer 2.0 elements that extended an element and used super.template to wrap/modify its super class template assuming super.template returned an HTMLTemplateElement.

As such, we propose to deprecate Polymer.Element's support for static get template() returning strings, such that super.template is guaranteed to return an HTMLTemplateElement, and never a string. In its place, we'll provide a html tagged template literal tag function that does the string -> template conversion, and modulizer will be changed to wrap template strings with html automatically.

This approach solves both the backwards-compatibility problem mentioned above, eliminates the ambiguously-typed nature of the current template API, and also has an extra benefit of providing a hint to code editors to syntax-highlight the template string as HTML (Sublime, Atom, and Github apparently already do this automatically, and VS Code has a plugin to do so).

In addition, the html tag function should have a small amount of sugar to allow creating holes in the template, so that subclassers can override those with html-tagged strings (which return templates) and have the hole values interpolated as strings (via innerHTML) before being converted to a template, e.g.:

Super class (provides a template with header and footer "holes"):

class SuperClass extends Polymer.Element {
  static get template() {
    return html`
      <div>${this.headerTemplate}</div>
      [[myProp.stuffThatGoesHere]]
      <div>${this.footerTemplate}</div>
    `;
  }
  static get headerTemplate() { return html`<h1>Header</h1>` }
  static get footerTemplate() { return html`<h1>Footer</h1>` }
}

Sub-class (both wraps the super template, and overrides the header/footer "holes"):

class SubClass extends SuperClass {
  static get template() {
    return html`
      <div class="frame">${super.template}</div>
    `;
  }
  static get headerTemplate() { return html`<h2>Sub-header</h2>` }
  static get footerTemplate() { return html`<h2>Sub-footer</h2>` }
}

To make the examples above work, the html tag function must take the innerHTML of any interpolated values that are HTMLElements; this is the only sugar proposed, other than taking the final interpolated string and parsing it into a new HTMLTemplateElement.

Note, the html tag function described here to be shipped with Polymer (which simply returns a vanilla HTMLTemplateElement) should not be confused with the html tag function provided with the lit-html library, which is similar in concept but separate in implementation. I think the benefits of de-facto standard HTML syntax highlighting in editors outweighs the potential confusion.

Versions

• Polymer: v2

[justinfagnani]

I presume we'd hang this tag directly off the Polymer namespace?

To trigger syntax highlighting in editors, we'd probably need a pattern like:

const html = Polymer.html;

class SuperClass extends Polymer.Element {
  template = html`...`;
}

[kevinpschaaf]

Eh, I don't really think anyone should bother using it unless they're using 3.0, where it's not an issue because they're importing it. But yeah, we'd hang it on Polymer.html so it's modulizer-ified into just an html named export.

[justinfagnani]

Ah, good point

[hadriann]

Is lit-html usable with Polymer 3 at this point?

[justinfagnani]

@Hadrian this issue isn't related to lit-html. It's just about adding a template tag in Polymer to create Polymer HTML templates and trigger syntax highlighting.