Polymer : Light DOM vs Local DOM

Question

What is the difference between Polymer's light DOM and local DOM? From the docs(1):

The DOM that an element creates and manages is called its local DOM. This is distinct from the element's children which are sometimes called its light DOM for clarity.

This doesn't seem to help much. Isn't the light DOM supposed to contain the children and if so what does the local DOM contain?

[1] https://www.polymer-project.org/1.0/docs/devguide/local-dom

Answer 1

Here's an example to explain the difference. Suppose you have the following custom element:

<dom-module id="x-foo">

  <template>
    <div>I am local dom</div>
    <content></content>
  </template>

  <script>
    Polymer({
      is: 'x-foo'
    });
  </script>

</dom-module>

And you use it like this in your document:

<x-foo>I am light dom</x-foo>

What ever you put into the template of the element is local dom. What you put as children to your custom element when you use it is light dom. So, the local dom is determined by the creator of the element, while the light dom is set by the user of the element. Of course, when you both create and use your own custom elements you have some flexibility what to put where.

Answer 2

If you create a component <a-component>, then it has its own markup (it's template) which is the local DOM. The template can contain <content></content> tags (one unnamed and multiple named ones) where children are projected to. Content added as children is shown in the light DOM.

When we have an <a-component> with it's local DOM

<dom-module id="a-component">
  <template>
    <div>A</div> 
    <content></content>
    <div>B</div>
  </template>
</dom-module> 

and we use it like

<a-component>
  <div>C</div>
</a-component>

then <div>C</div> is shown in the light DOM. The resulting DOM in the browser then looks like

    <div>A</div> 
    <div>C</div>
    <div>B</div>

Where <div>A</div> and <div>B</div> are called the local DOM when seen from within <a-component> and shady or shadow DOM when seen from the outside of the component and <div>C</div> is in the light DOM.

If we take again this markup we would add to the page

<a-component>
  <div>C</div>
</a-component>

You see that <div>C</div> is directly added by the user of the component while <div>A</div> and <div>B</div> are hidden (in the shadow) and revealed only later when <a-component> is processed by the browser.

The distinction of shady and shadow is about if full shadow DOM is enabled or not for Polymer. Shady emulates shadow to some degree but with some notable differences, this is why it got a different name.