src/lib/template/dom-bind.html

<!--
@license
Copyright (c) 2014 The Polymer Project Authors. All rights reserved.
This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt
The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
Code distributed by Google as part of the polymer project is also
subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt
-->

<!--

Polymer's binding features are only available within templates that are managed
by Polymer.  As such, these features are available in templates used to define
Polymer elements, for example, but not for elements placed directly in the main
document.

In order to use Polymer bindings without defining a new custom element, elements
utilizing bindings may be wrapped with the `dom-bind` template extension.
This template will immediately stamp itself into the main document and bind
elements to the template itself as the binding scope.

```html
<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <script src="components/webcomponentsjs/webcomponents-lite.js"></script>
  <link rel="import" href="components/polymer/polymer.html">
  <link rel="import" href="components/core-ajax/core-ajax.html">

</head>
<body>

  <template is="dom-bind">

    <core-ajax url="http://..." lastresponse="{{data}}"></core-ajax>

    <template is="dom-repeat" items="{{data}}">
        <div><span>{{item.first}}</span> <span>{{item.last}}</span></div>
    </template>

  </template>

</body>
</html>
```

-->

<link rel="import" href="../imports-status.html">

<script>

  Polymer({

    /**
     * Fired whenever DOM is stamped by this template (rendering
     * will be deferred until all HTML imports have resolved).
     *
     * @event dom-change
     */

    is: 'dom-bind',

    extends: 'template',

    created: function() {
      // Ensure dom-bind doesn't stamp until all possible dependencies
      // have resolved
      Polymer.ImportStatus.whenLoaded(this._markImportsReady.bind(this));
    },

    _ensureReady: function() {
      if (!this._readied) {
        this._readySelf();
      }
    },

    _markImportsReady: function() {
      this._importsReady = true;
      this._ensureReady();
    },

    _registerFeatures: function() {
      this._prepConstructor();
    },

    _insertChildren: function() {
      var parentDom = Polymer.dom(Polymer.dom(this).parentNode);
      parentDom.insertBefore(this.root, this);
    },

    _removeChildren: function() {
      if (this._children) {
        for (var i=0; i<this._children.length; i++) {
          this.root.appendChild(this._children[i]);
        }
      }
    },

    _initFeatures: function() {
      // defer _initFeatures and stamping until after attached, to support
      // document.createElement('template', 'dom-bind') use case,
      // where template content is filled in after creation
    },

    // avoid scoping elements as we expect dom-bind output to be in the main
    // document
    _scopeElementClass: function(element, selector) {
      if (this.dataHost) {
        return this.dataHost._scopeElementClass(element, selector);
      } else {
        return selector;
      }
    },

    _prepConfigure: function() {
      var config = {};
      for (var prop in this._propertyEffects) {
        config[prop] = this[prop];
      }
      // Pass values set before attached as initialConfig to _setupConfigure
      this._setupConfigure = this._setupConfigure.bind(this, config);
    },

    attached: function() {
      if (this._importsReady) {
        this.render();
      }
    },

    detached: function() {
      this._removeChildren();
    },

    /**
     * Forces the element to render its content. This is typically only 
     * necessary to call if HTMLImports with the async attribute are used.
     */
    render: function() {
      this._ensureReady();
      if (!this._children) {
        this._template = this;
        this._prepAnnotations();
        this._prepEffects();
        this._prepBehaviors();
        this._prepConfigure();
        this._prepBindings();
        Polymer.Base._initFeatures.call(this);
        this._children = Array.prototype.slice.call(this.root.childNodes);
      }
      this._insertChildren();
      this.fire('dom-change');
    }

  });

</script>