Add WebComponents.whenReady

A callback based timing function equivalent to the WebComponentsReady event

README.md

@@ -88,6 +88,17 @@ window.addEventListener('WebComponentsReady', function(e) {
 });
 ```
 
+### `WebComponents.whenReady`
+
+Similar to the `WebComponentsReady` event, the `WebComponents.whenReady` can be given a callback to call when elements are ready to interact with.
+
+```js
+WebComponents.whenReady(function() {
+  // imports are loaded and elements are registered
+  console.log('Components are ready');
+});
+```
+
 ## Known Issues
 
   * [Custom element's constructor property is unreliable](#constructor)

src/WebComponents/build-lite.json

@@ -7,5 +7,6 @@
   "../CustomElements/build.json",
   "../Template/Template.js",
   "dom.js",
-  "unresolved.js"
+  "unresolved.js",
+  "whenready.js"
 ]

src/WebComponents/build.json

@@ -11,5 +11,6 @@
   "lang.js",
   "dom.js",
   "unresolved.js",
+  "whenready.js",
   "bc.js"
 ]

src/WebComponents/whenready.js

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright (c) 2015 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
+ */
+
+(function(scope) {
+
+  // call a callback when WebComponents are ready in the document
+  // call immediately if Web Components are in a good state already
+  function whenReady(callback) {
+    if (!window.CustomElements.ready) {
+      var after = function after() {
+        window.removeEventListener('WebComponentsReady', after);
+        callback();
+      };
+      window.addEventListener('WebComponentsReady', after);
+    } else {
+      callback();
+    }
+  }
+
+  scope.whenReady = whenReady;
+
+})(window.WebComponents);

tests/WebComponents/html/web-components.html

@@ -22,9 +22,17 @@
       window.addEventListener('HTMLImportsLoaded', function() {
         window.importsOk = true;
       });
-      test('expected boot', function() {
+      test('expected boot', function(done) {
         chai.assert.ok(window.importsOk, 'WebComponentsReady without HTMLImportsLoaded');
         chai.assert.ok(window.importTest, 'import failed to set global value');
+
+        WebComponents.whenReady(function() {
+          chai.assert.ok(window.importTest, 'import failed to set global value');
+          // can be called twice
+          WebComponents.whenReady(function() {
+            done();
+          });
+        });
       });
     </script>
   </body>

webcomponents-lite.js

@@ -58,7 +58,8 @@
     'Template/Template.js',
     // these scripts are loaded here due to polyfill timing issues
     'WebComponents/dom.js',
-    'WebComponents/unresolved.js'
+    'WebComponents/unresolved.js',
+    'WebComponents/whenready.js'
   ];
 
   var src = script.getAttribute('src');

webcomponents.js

@@ -84,6 +84,7 @@
       // these scripts are loaded here due to polyfill timing issues
       'WebComponents/dom.js',
       'WebComponents/unresolved.js',
+      'WebComponents/whenready.js',
       // back compat.
       'WebComponents/bc.js'
     ]