Polymer's Fifty Shades of DOM

polymer-50-shades-of-dom.html

<!--
HOWTO do kinky stuff with Polymer and jQuery

Read this is you went through https://www.polymer-project.org/1.0/docs/devguide/local-dom.html
and you're still not sure how to play with jQuery inside Polymer components.
-->

<link rel="import" href="/components/polymer/polymer.html">

<dom-module id="my-component">

  <template>
    <!--
    The DOM made up of the actual element node and it's children
    (the children of <template> actually), is what is called the
    "Local DOM".
    
    Possible implementations of the Local DOM are:
    - Shadow DOM, how things are actually supposed to work in
      fully compliant browsers
    - Shady DOM, a partial-polyfill for Shadow DOM that is actually
      the default mode in Polymer 1.0 (even in browsers that support
      Shadow DOM!)
    -->
    <h1>My Component</h1>

    <content>
      <!--
      The "Light DOM" refers to the acutal children of the custom
      element node, as defined in the HTML file that makes use of
      this component.
      
      The Light DOM is rendered inside the Local DOM by means of
      the <content> tag.
      -->
    </content>
  </template>

  <script>
    Polymer({
      is: 'my-component',

      ready: function () {
        Polymer.dom(this); // Light DOM (<content> tag / actual components)
        this; // WRONG way to reference Light DOM: actually ends up accessing the Local DOM, probably in a wrong way

        Polymer.dom(this.root); // Local DOM (<template> tag)
        this.root; // WRONG way to reference Local DOM: doesn't work at all, imho a good thing, as things are already confusing as hell...

        $(this); // WRONG way to use jQuery on the Light DOM: actually ends up accessing the Local DOM, probably in a wrong way

        /**
         * NOTE: There is no documentation explicitly confirming that the way
         * described below is the "correct" way to use jQuery inside Polymer
         * components, this is simply what I've arrived at through common sense
         * and personal trial-and-error!
         */
        $(Polymer.dom(this)); // (right?) way to use jQuery on the Light DOM
        $(Polymer.dom(this.root)); // (right?) way to use jQuery on the Local DOM

        /**
         * Just play arround by inspecting the .childNodes or .children() of the
         * objects above in the browser console, to convince yourselves that what
         * I wrote is true :)
         */
        debugger;
      }
    });
  </script>

</dom-module>