Web components.md

Confusing Components

Do I need all four parts?

• Custom Elements
• Shadow DOM
• HTML Imports
• HTML Templates

I'm confused as to which bits I need supported. Do I need all of them to blindy create and use other components?

EG, if I want to create <jack-element></jack-element> that has the content <p>My name is Jack</p> and some JS attached, which of the above are required?

How do I polyfill web components?

• do I need to polyfill all the "parts" ?
• Is it best to just use the full polyfill from https://github.com/webcomponents/webcomponentsjs/tree/v0.7.22 ?
• Or is it best to pick the polyfills for each individual bit that I need? How would I do that?

What is Polymer?

• Is it a collection of polyfills for the above?
• Is it a full on library / framework for building web applications that happens to first polyfill over components?
• If I use Polymer do I lock myself into using it in the future, event when components become fully supported?

CSS

• Can I have scoped CSS for a component (akin to CSS modules in React)

I have similar question marks in my head. I need a clearer understanding, some sort of a flow chart, as to which to use when and which one I need. A real, actual, literal flow chart might be a good idea actually. :) As in: do you need to do X? then you need Y, etc. and that includes every aspect of using components, including support.

TLDR answers...

Do I need all four parts?

No. But the idea is that each spec provides a primitive/API for building reusable, "encapsulated", and declarative components. Using all of them together makes things easier.

http://webcomponents.org/polyfills/ discusses each API and what they're useful for:

• Custom elements - defining new html tags and associating behavior with them (js api)
• Shadow DOM - scoping CSS to an element. Creating local DOM for an element, hidden away from the page. Composition tool for composition elements together (e.g. how <select> knows how to render <option> tags as a dropdown widget).
• HTML Imports - bundle related JS/HTML/CSS together. Think of this as a way to package all the component's goodies/implementation together. Users of your component load a single URL and begin using the tag!
• <template> - creates a chunk of DOM that content is 100% inert at page load but parsed and ready to be used.

The articles on html5rocks.com are still among the best out there for intro material: http://www.html5rocks.com/en/search?q=web+components.

<jack-element></jack-element> that has the content <p>My name is Jack</p> and some JS attached, which of the above are required?

Really, only Custom elements (to create the tag "jack-element" and attach a JS API). Shadow DOM would be useful to make <p>My name is Jack</p> internal and local the element. HTML Imports would make bundling + loading that related JS/HTML/CSS, easier.

Your example (all use shadow dom v0 and custom elements v0):

<!-- template: useful for stashing markup that will be used over and over again. -->
<template id="jacktemplate">
  <style>p { color: orange; }</style>
  <p>My name is Jack</p>
</template>

<script>
// Define a JS API for <jack-element> and register it in the browser.
class JackElement extends HTMLElement {
  attachedCallback() {
    const t = document.querySelector('#jacktemplate');
    const templateInstance = t.content.cloneNode(true);

    // Creating Shadow DOM from a <template>, and attaching the shadow dom to this element.
    this.createShadowRoot().appendChild(templateInstance);
  }
}
document.registerElement('jack-element', MyElement);
</script>

I would then bundle all this code up in an .html file and use this in my app to use the tag:

<script src="webcomponents.js" async>
<link rel="import" href="jackelement.html" async>

How do I polyfill web components?

https://github.com/webcomponents/webcomponentsjs/tree/v0.7.22 provides everything you need. You can build/use each spec'd polyfill by itself, but most uses will just want all of them together.

What is Polymer?

TL;DR: Polymer is a sugaring library for creating web components, declaratively. The same team also happens to maintain the webcomponents.js polyfills and vends collections of high quality useful web components. Those are written in Polymer, but Polymer itself is just a library.

These are useful:

• http://webcomponents.org/articles/a-quick-polymer-introduction/
• https://www.polymer-project.org/1.0/docs/devguide/quick-tour

CSS

Shadow DOM is for scoping CSS to an element and creating local DOM, "hidden" from the rest of the page. It's also a composition tool.

@ebidel that helps so much, thank you! I really appreciate it. That cleared up a lot of things in my head.