added `render` method to dom-bind which can be called when async impo…

…rts are used; documented template render functions

@@ -68,7 +68,18 @@
     created: function() {
       // Ensure dom-bind doesn't stamp until all possible dependencies
       // have resolved
-      Polymer.ImportStatus.whenLoaded(this._readySelf.bind(this));
+      Polymer.ImportStatus.whenLoaded(this._markImportsReady.bind(this));
+    },
+
+    _ensureReady: function() {
+      if (!this._readied) {
+        this._readySelf();
+      }
+    },
+
+    _markImportsReady: function() {
+      this._importsReady = true;
+      this._ensureReady();
     },
 
     _registerFeatures: function() {
@@ -114,6 +125,22 @@
     },
 
     attached: function() {
+      if (this._importsReady) {
+        this.render();
+      }
+    },
+
+    detached: function() {
+      this._removeChildren();
+      this.fire('dom-change');
+    },
+
+    /**
+     * 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();
@@ -126,10 +153,6 @@
       }
       this._insertChildren();
       this.fire('dom-change');
-    },
-
-    detached: function() {
-      this._removeChildren();
     }
 
   });

@@ -84,6 +84,13 @@
       }
     },
 
+    /**
+     * Forces the element to render its content. Normally rendering is 
+     * asynchronous to a provoking change. This is done for efficiency so 
+     * that multiple changes trigger only a single render. The render method 
+     * should be called if, for example, template rendering is required to 
+     * validate application state.
+     */
     render: function() {
       this._flushTemplates();
     },

@@ -302,6 +302,13 @@
       }
     },
 
+    /**
+     * Forces the element to render its content. Normally rendering is 
+     * asynchronous to a provoking change. This is done for efficiency so 
+     * that multiple changes trigger only a single render. The render method 
+     * should be called if, for example, template rendering is required to 
+     * validate application state.
+     */
     render: function() {
       // Queue this repeater, then flush all in order
       this._fullRefresh = true;

@@ -168,6 +168,43 @@
         assert(!document.body.contains(el2));
       });
 
+      test('dom-bind distributed when inserted in element attached', function(done) {
+        var el = document.createElement('x-attach-dom-bind');
+        document.body.appendChild(el);
+        setTimeout(function() {
+          assert.equal(el.$.local.textContent, 'hey', 'dom-bind did not distribute');
+          document.body.removeChild(el);
+          done();
+        })
+      });
+
+      test('dom-bind distributed when inserted in element attached (flush)', function() {
+        var el = document.createElement('x-attach-dom-bind');
+        document.body.appendChild(el);
+        Polymer.dom.flush();
+        assert.equal(el.$.local.textContent, 'hey', 'dom-bind did not distribute');
+        document.body.removeChild(el);
+      });
+
+      test('dom-bind distributed when inserted dynamically', function(done) {
+        var el = document.createElement('x-compose');
+        document.body.appendChild(el);
+        Polymer.dom.flush();
+        setTimeout(function() {
+          var t = document.createElement('template', 'dom-bind'),
+          span = document.createElement('span');
+          span.innerHTML = '{{hello}}';
+          t.content.appendChild(span);
+          t.hello = 'hey';
+          Polymer.dom(el.$.local).appendChild(t);
+          setTimeout(function() {
+            assert.equal(el.textContent, 'hey', 'dom-bind did not distribute');
+            document.body.removeChild(el);
+            done();
+          });
+        });
+      });
+
     });
 
     suite('timing', function() {