Fixes #2125: adds a register method to dom-module to support imperati…

…ve creation.
Polymer · Jul 21, 2015 · 861f4aa · 861f4aa
1 parent 8134fbf
commit 861f4aa
Show file tree

Hide file tree

Showing 2 changed files with 70 additions and 21 deletions.
diff --git a/src/lib/dom-module.html b/src/lib/dom-module.html
@@ -4,36 +4,76 @@
 
   var modules = {};
 
+  /**
+   * The `dom-module` element registers the dom it contains to the name given
+   * by the module's id attribute. It provides a unified database of dom 
+   * accessible via any dom-module element. Use the `import(id, selector)`
+   * method to locate dom within this database. For example,
+   *
+   * <dom-module id="foo">
+   *   <img src="stuff.png">
+   * </dom-module>
+   *
+   * Then in code in some other location that cannot access the dom-module above
+   *
+   * var img = document.createElement('dom-module').import('foo', 'img');
+   *
+   */
   var DomModule = function() {
     return document.createElement('dom-module');
   };
 
   DomModule.prototype = Object.create(HTMLElement.prototype);
 
-  DomModule.prototype.constructor = DomModule;
+  Polymer.Base.extend(DomModule.prototype, {
 
-  DomModule.prototype.createdCallback = function() {
-    var id = this.id || this.getAttribute('name') || this.getAttribute('is');
-    if (id) {
-      this.id = id;
-      modules[id] = this;
-    }
-  };
+    constructor: DomModule,
 
-  DomModule.prototype.import = function(id, slctr) {
-    var m = modules[id];
-    if (!m) {
-      // If polyfilling, a script can run before a dom-module element
-      // is upgraded. We force the containing document to upgrade
-      // and try again to workaround this polyfill limitation.
-      forceDocumentUpgrade();
-      m = modules[id];
-    }
-    if (m && slctr) {
-      m = m.querySelector(slctr);
+    createdCallback: function() {
+      this.register();
+    },
+
+    /**
+     * Registers the dom-module at a given id. This method should only be called
+     * when a dom-module is imperatively created. For 
+     * example, `document.createElement('dom-module').register('foo')`.
+     * @method register
+     * @param {String} id The id at which to register the dom-module.
+     */
+    register: function(id) {
+      var id = id || this.id || 
+        this.getAttribute('name') || this.getAttribute('is');
+      if (id) {
+        this.id = id;
+        modules[id] = this;
+      }
+    },
+
+    /**
+     * Retrieves the dom specified by `selector` in the module specified by 
+     * `id`. For example, this.import('foo', 'img');
+     * @method register
+     * @param {String} id
+     * @param {String} selector
+     * @return {Object} Returns the dom which matches `selector` in the module
+     * at the specified `id`.
+     */
+    import: function(id, selector) {
+      var m = modules[id];
+      if (!m) {
+        // If polyfilling, a script can run before a dom-module element
+        // is upgraded. We force the containing document to upgrade
+        // and try again to workaround this polyfill limitation.
+        forceDocumentUpgrade();
+        m = modules[id];
+      }
+      if (m && selector) {
+        m = m.querySelector(selector);
+      }
+      return m;
     }
-    return m;
-  };
+
+  });
 
   // NOTE: HTMLImports polyfill does not
   // block scripts on upgrading elements. However, we want to ensure that

diff --git a/test/unit/micro.html b/test/unit/micro.html
@@ -108,6 +108,15 @@
       assert.isTrue(Polymer.isInstance(el));
     });
 
+    test('imperative dom-module', function() {
+      var d = document.createElement('dom-module');
+      var c = document.createElement('div');
+      d.appendChild(c);
+      d.register('my-module');
+      var lookup = document.createElement('dom-module');
+      assert.equal(lookup.import('my-module', 'div'), c);
+    });
+
   });
 
 </script>