Provide plugin DOM hooks for components

In order to simplify custom components usage by plugins, provide DOM hooks for plugin-defined custom components. Previously DOM hook API was only provided for API-generated placeholder elements. Other changes: - endpoint insertions now can be performed at any point in time and will retrospectively attached to DOM for fully initialized endpoints as well - helper method for querying all hook instances - getLastAttached() method returns a promise to simplify singleton element setup and usage (e.g. popups) Change-Id: I1c95146f76ee52bea3b9e01b666112ce6448efcd
2017-08-15 08:02:58 -07:00 · 2017-08-15 08:02:58 -07:00 · ab491f77a0
commit ab491f77a0
parent ebf009cc5c
10 changed files with 327 additions and 70 deletions
--- a/Documentation/dev-plugins-pg.txt
+++ b/Documentation/dev-plugins-pg.txt
@ -45,14 +45,14 @@ hook is a custom element that is instantiated for the plugin endpoint. In the
 decoration case, a hook is set with a `content` attribute that points to the DOM
 element.

-1. Get the DOM hook API instance via `plugin.getDomHook(endpointName)`
+1. Get the DOM hook API instance via `plugin.hook(endpointName)`
 2. Set up an `onAttached` callback
 3. Callback is called when the hook element is created and inserted into DOM
 4. Use element.content to get UI element

 ``` js
 Gerrit.install(function(plugin) {
-  const domHook = plugin.getDomHook('reply-text');
+  const domHook = plugin.hook('reply-text');
  domHook.onAttached(element => {
    if (!element.content) { return; }
    // element.content is a reply dialog text area.
@ -70,7 +70,7 @@ NOTE: TODO: Insert link to the full endpoints API.

 ``` js
 Gerrit.install(function(plugin) {
-  const domHook = plugin.getDomHook('reply-text');
+  const domHook = plugin.hook('reply-text');
  domHook.onAttached(element => {
    if (!element.content) { return; }
    element.content.style.border = '1px red dashed';
@ -86,7 +86,7 @@ option.

 ``` js
 Gerrit.install(function(plugin) {
-  const domHook = plugin.getDomHook('header-title', {replace: true});
+  const domHook = plugin.hook('header-title', {replace: true});
  domHook.onAttached(element => {
    element.appendChild(document.createElement('my-site-header'));
  });
--- a/polygerrit-ui/app/elements/plugins/gr-dom-hooks/gr-dom-hooks.js
+++ b/polygerrit-ui/app/elements/plugins/gr-dom-hooks/gr-dom-hooks.js
@ -14,49 +14,122 @@
 (function(window) {
  'use strict';

-  function GrDomHooks(plugin) {
+  function GrDomHooksManager(plugin) {
    this._plugin = plugin;
    this._hooks = {};
  }

-  GrDomHooks.prototype._getName = function(endpointName) {
-    return this._plugin.getPluginName() + '-autogenerated-' + endpointName;
+  GrDomHooksManager.prototype._getHookName = function(endpointName,
+      opt_moduleName) {
+    if (opt_moduleName) {
+      return endpointName + ' ' + opt_moduleName;
+    } else {
+      return this._plugin.getPluginName() + '-autogenerated-' + endpointName;
+    }
  };

-  GrDomHooks.prototype.getDomHook = function(endpointName) {
-    const hookName = this._getName(endpointName);
+  GrDomHooksManager.prototype.getDomHook = function(endpointName,
+      opt_moduleName) {
+    const hookName = this._getHookName(endpointName, opt_moduleName);
    if (!this._hooks[hookName]) {
-      this._hooks[hookName] = new GrDomHook(hookName);
+      this._hooks[hookName] = new GrDomHook(hookName, opt_moduleName);
    }
    return this._hooks[hookName];
  };

-  function GrDomHook(hookName) {
+  function GrDomHook(hookName, opt_moduleName) {
+    this._instances = [];
    this._callbacks = [];
-    // Expose to closure.
-    const callbacks = this._callbacks;
-    this._componentClass = Polymer({
+    if (opt_moduleName) {
+      this._moduleName = opt_moduleName;
+    } else {
+      this._moduleName = hookName;
+      this._createPlaceholder(hookName);
+    }
+  }
+
+  GrDomHook.prototype._createPlaceholder = function(hookName) {
+    Polymer({
      is: hookName,
      properties: {
        plugin: Object,
        content: Object,
      },
-      attached() {
-        callbacks.forEach(callback => {
-          callback(this);
-        });
-      },
    });
-  }
+  };

+  GrDomHook.prototype.handleInstanceDetached = function(instance) {
+    const index = this._instances.indexOf(instance);
+    if (index !== -1) {
+      this._instances.splice(index, 1);
+    }
+  };
+
+  GrDomHook.prototype.handleInstanceAttached = function(instance) {
+    this._instances.push(instance);
+    this._callbacks.forEach(callback => callback(instance));
+  };
+
+  /**
+   * Get instance of last DOM hook element attached into the endpoint.
+   * Returns a Promise, that's resolved when attachment is done.
+   * @return {!Promise<!Element>}
+   */
+  GrDomHook.prototype.getLastAttached = function() {
+    if (this._instances.length) {
+      return Promise.resolve(this._instances.slice(-1)[0]);
+    }
+    if (!this._lastAttachedPromise) {
+      let resolve;
+      const promise = new Promise(r => resolve = r);
+      this._callbacks.push(resolve);
+      this._lastAttachedPromise = promise.then(element => {
+        this._lastAttachedPromise = null;
+        const index = this._callbacks.indexOf(resolve);
+        if (index !== -1) {
+          this._callbacks.splice(index, 1);
+        }
+        return element;
+      });
+    }
+    return this._lastAttachedPromise;
+  };
+
+  /**
+   * Get all DOM hook elements.
+   */
+  GrDomHook.prototype.getAllAttached = function() {
+    return this._instances;
+  };
+
+  /**
+   * Install a new callback to invoke when a new instance of DOM hook element
+   * is attached.
+   * @param {function(Element)} callback
+   */
  GrDomHook.prototype.onAttached = function(callback) {
    this._callbacks.push(callback);
    return this;
  };

+  /**
+   * Name of DOM hook element that will be installed into the endpoint.
+   */
  GrDomHook.prototype.getModuleName = function() {
-    return this._componentClass.prototype.is;
+    return this._moduleName;
  };

-  window.GrDomHooks = GrDomHooks;
+  GrDomHook.prototype.getPublicAPI = function() {
+    const result = {};
+    const exposedMethods = [
+      'onAttached', 'getLastAttached', 'getAllAttached', 'getModuleName',
+    ];
+    for (const p of exposedMethods) {
+      result[p] = this[p].bind(this);
+    }
+    return result;
+  };
+
+  window.GrDomHook = GrDomHook;
+  window.GrDomHooksManager = GrDomHooksManager;
 })(window);
--- a/polygerrit-ui/app/elements/plugins/gr-dom-hooks/gr-dom-hooks_test.html
+++ b/polygerrit-ui/app/elements/plugins/gr-dom-hooks/gr-dom-hooks_test.html
@ -33,28 +33,110 @@ limitations under the License.

 <script>
  suite('gr-dom-hooks tests', () => {
+    const PUBLIC_METHODS =
+        ['onAttached', 'getLastAttached', 'getAllAttached', 'getModuleName'];
+
    let instance;
    let sandbox;
+    let hook;
+    let hookInternal;

    setup(() => {
      sandbox = sinon.sandbox.create();
      let plugin;
      Gerrit.install(p => { plugin = p; }, '0.1',
          'http://test.com/plugins/testplugin/static/test.js');
-      instance = new GrDomHooks(plugin);
+      instance = new GrDomHooksManager(plugin);
    });

    teardown(() => {
      sandbox.restore();
    });

-    test('defines a Polymer components', () => {
-      const onAttachedSpy = sandbox.spy();
-      instance.getDomHook('foo-bar').onAttached(onAttachedSpy);
-      const hookName = Object.keys(instance._hooks).pop();
-      assert.equal(hookName, 'testplugin-autogenerated-foo-bar');
-      const el = fixture('basic').appendChild(document.createElement(hookName));
-      assert.isTrue(onAttachedSpy.calledWithExactly(el));
+    suite('placeholder', () => {
+      setup(()=>{
+        sandbox.stub(GrDomHook.prototype, '_createPlaceholder');
+        hookInternal = instance.getDomHook('foo-bar');
+        hook = hookInternal.getPublicAPI();
+      });
+
+      test('public hook API has only public methods', () => {
+        assert.deepEqual(Object.keys(hook), PUBLIC_METHODS);
+      });
+
+      test('registers placeholder class', () => {
+        assert.isTrue(hookInternal._createPlaceholder.calledWithExactly(
+            'testplugin-autogenerated-foo-bar'));
+      });
+
+      test('getModuleName()', () => {
+        const hookName = Object.keys(instance._hooks).pop();
+        assert.equal(hookName, 'testplugin-autogenerated-foo-bar');
+        assert.equal(hook.getModuleName(), 'testplugin-autogenerated-foo-bar');
+      });
+    });
+
+    suite('custom element', () => {
+      setup(() => {
+        hookInternal = instance.getDomHook('foo-bar', 'my-el');
+        hook = hookInternal.getPublicAPI();
+      });
+
+      test('public hook API has only public methods', () => {
+        assert.deepEqual(Object.keys(hook), PUBLIC_METHODS);
+      });
+
+      test('getModuleName()', () => {
+        const hookName = Object.keys(instance._hooks).pop();
+        assert.equal(hookName, 'foo-bar my-el');
+        assert.equal(hook.getModuleName(), 'my-el');
+      });
+
+      test('onAttached', () => {
+        const onAttachedSpy = sandbox.spy();
+        hook.onAttached(onAttachedSpy);
+        const [el1, el2] = [
+          document.createElement(hook.getModuleName()),
+          document.createElement(hook.getModuleName()),
+        ];
+        hookInternal.handleInstanceAttached(el1);
+        hookInternal.handleInstanceAttached(el2);
+        assert.isTrue(onAttachedSpy.firstCall.calledWithExactly(el1));
+        assert.isTrue(onAttachedSpy.secondCall.calledWithExactly(el2));
+      });
+
+      test('getAllAttached', () => {
+        const [el1, el2] = [
+          document.createElement(hook.getModuleName()),
+          document.createElement(hook.getModuleName()),
+        ];
+        el1.textContent = 'one';
+        el2.textContent = 'two';
+        hookInternal.handleInstanceAttached(el1);
+        hookInternal.handleInstanceAttached(el2);
+        assert.deepEqual([el1, el2], hook.getAllAttached());
+        hookI.handleInstanceDetached(el1);
+        assert.deepEqual([el2], hook.getAllAttached());
+      });
+
+      test('getLastAttached', () => {
+        const beforeAttachedPromise = hook.getLastAttached().then(
+            el => assert.strictEqual(el1, el));
+        const [el1, el2] = [
+          document.createElement(hook.getModuleName()),
+          document.createElement(hook.getModuleName()),
+        ];
+        el1.textContent = 'one';
+        el2.textContent = 'two';
+        hookInternal.handleInstanceAttached(el1);
+        hookInternal.handleInstanceAttached(el2);
+        const afterAttachedPromise = hook.getLastAttached().then(
+            el => assert.strictEqual(el2, el));
+        return Promise.all([
+          beforeAttachedPromise,
+          afterAttachedPromise,
+        ]);
+      });
    });
  });
 </script>
--- a/polygerrit-ui/app/elements/plugins/gr-endpoint-decorator/gr-endpoint-decorator.js
+++ b/polygerrit-ui/app/elements/plugins/gr-endpoint-decorator/gr-endpoint-decorator.js
@ -19,6 +19,17 @@

    properties: {
      name: String,
+      /** @type {!Map} */
+      _domHooks: {
+        type: Map,
+        value() { return new Map(); },
+      },
+    },
+
+    detached() {
+      for (const [el, domHook] of this._domHooks) {
+        domHook.handleInstanceDetached(el);
+      }
    },

    _import(url) {
@ -31,33 +42,48 @@
      const el = document.createElement(name);
      el.plugin = plugin;
      el.content = this.getContentChildren()[0];
-      return Polymer.dom(this.root).appendChild(el);
+      this._appendChild(el);
+      return el;
    },

    _initReplacement(name, plugin) {
      this.getContentChildren().forEach(node => node.remove());
      const el = document.createElement(name);
      el.plugin = plugin;
-      return Polymer.dom(this.root).appendChild(el);
+      this._appendChild(el);
+      return el;
+    },
+
+    _appendChild(el) {
+      Polymer.dom(this.root).appendChild(el);
+    },
+
+    _initModule({moduleName, plugin, type, domHook}) {
+      let el;
+      switch (type) {
+        case 'decorate':
+          el = this._initDecoration(moduleName, plugin);
+          break;
+        case 'replace':
+          el = this._initReplacement(moduleName, plugin);
+          break;
+      }
+      if (el) {
+        domHook.handleInstanceAttached(el);
+      }
+      this._domHooks.set(el, domHook);
    },

    ready() {
+      Gerrit._endpoints.onNewEndpoint(this.name, this._initModule.bind(this));
      Gerrit.awaitPluginsLoaded().then(() => Promise.all(
          Gerrit._endpoints.getPlugins(this.name).map(
              pluginUrl => this._import(pluginUrl)))
-      ).then(() => {
-        const modulesData = Gerrit._endpoints.getDetails(this.name);
-        for (const {moduleName, plugin, type} of modulesData) {
-          switch (type) {
-            case 'decorate':
-              this._initDecoration(moduleName, plugin);
-              break;
-            case 'replace':
-              this._initReplacement(moduleName, plugin);
-              break;
-          }
-        }
-      });
+      ).then(() =>
+        Gerrit._endpoints
+            .getDetails(this.name)
+            .forEach(this._initModule, this)
+      );
    },
  });
 })();
--- a/polygerrit-ui/app/elements/plugins/gr-endpoint-decorator/gr-endpoint-decorator_test.html
+++ b/polygerrit-ui/app/elements/plugins/gr-endpoint-decorator/gr-endpoint-decorator_test.html
@ -34,10 +34,20 @@ limitations under the License.
    let sandbox;
    let element;
    let plugin;
+    let domHookStub;

    setup(done => {
+      Gerrit._endpoints = new GrPluginEndpoints();
+
      sandbox = sinon.sandbox.create();

+      domHookStub = {
+        handleInstanceAttached: sandbox.stub(),
+        handleInstanceDetached: sandbox.stub(),
+      };
+      sandbox.stub(
+          GrDomHooksManager.prototype, 'getDomHook').returns(domHookStub);
+
      // NB: Order is important.
      Gerrit.install(p => {
        plugin = p;
@ -45,11 +55,12 @@ limitations under the License.
        plugin.registerCustomComponent('foo', 'other-module', {replace: true});
      }, '0.1', 'http://some/plugin/url.html');

+      sandbox.stub(Gerrit, '_arePluginsLoaded').returns(true);
      sandbox.stub(Gerrit, 'awaitPluginsLoaded').returns(Promise.resolve());

      element = fixture('basic');
-      sandbox.stub(element, '_initDecoration');
-      sandbox.stub(element, '_initReplacement');
+      sandbox.stub(element, '_initDecoration').returns({});
+      sandbox.stub(element, '_initReplacement').returns({});
      sandbox.stub(element, 'importHref', (url, resolve) => resolve());

      flush(done);
@ -65,13 +76,39 @@ limitations under the License.
    });

    test('inits decoration dom hook', () => {
-      assert.isTrue(
-          element._initDecoration.calledWith('some-module', plugin));
+      assert.strictEqual(
+          element._initDecoration.lastCall.args[0], 'some-module');
+      assert.strictEqual(
+          element._initDecoration.lastCall.args[1], plugin);
    });

    test('inits replacement dom hook', () => {
-      assert.isTrue(
-          element._initReplacement.calledWith('other-module', plugin));
+      assert.strictEqual(
+          element._initReplacement.lastCall.args[0], 'other-module');
+      assert.strictEqual(
+          element._initReplacement.lastCall.args[1], plugin);
+    });
+
+    test('calls dom hook handleInstanceAttached', () => {
+      assert.equal(domHookStub.handleInstanceAttached.callCount, 2);
+    });
+
+    test('calls dom hook handleInstanceDetached', () => {
+      element.detached();
+      assert.equal(domHookStub.handleInstanceDetached.callCount, 2);
+    });
+
+    test('installs modules on late registration', done => {
+      domHookStub.handleInstanceAttached.reset();
+      plugin.registerCustomComponent('foo', 'noob-noob');
+      flush(() => {
+        assert.equal(domHookStub.handleInstanceAttached.callCount, 1);
+        assert.strictEqual(
+            element._initDecoration.lastCall.args[0], 'noob-noob');
+        assert.strictEqual(
+            element._initDecoration.lastCall.args[1], plugin);
+        done();
+      });
    });
  });
 </script>
--- a/polygerrit-ui/app/elements/plugins/gr-theme-api/gr-theme-api.js
+++ b/polygerrit-ui/app/elements/plugins/gr-theme-api/gr-theme-api.js
@ -22,7 +22,7 @@
  }

  GrThemeApi.prototype.setHeaderLogoAndTitle = function(logoUrl, title) {
-    this.plugin.getDomHook('header-title', {replace: true}).onAttached(
+    this.plugin.hook('header-title', {replace: true}).onAttached(
        element => {
          const customHeader =
                document.createElement('gr-custom-plugin-header');
--- a/polygerrit-ui/app/elements/shared/gr-js-api-interface/gr-change-reply-js-api.js
+++ b/polygerrit-ui/app/elements/shared/gr-js-api-interface/gr-change-reply-js-api.js
@ -49,7 +49,7 @@

  GrChangeReplyInterface.prototype.addReplyTextChangedCallback =
    function(handler) {
-      this.plugin.getDomHook('reply-text').onAttached(el => {
+      this.plugin.hook('reply-text').onAttached(el => {
        if (!el.content) { return; }
        el.content.addEventListener('value-changed', e => {
          handler(e.detail.value);
--- a/polygerrit-ui/app/elements/shared/gr-js-api-interface/gr-plugin-endpoints.js
+++ b/polygerrit-ui/app/elements/shared/gr-js-api-interface/gr-plugin-endpoints.js
@ -16,19 +16,32 @@

  function GrPluginEndpoints() {
    this._endpoints = {};
+    this._callbacks = {};
  }

+  GrPluginEndpoints.prototype.onNewEndpoint = function(endpoint, callback) {
+    if (!this._callbacks[endpoint]) {
+      this._callbacks[endpoint] = [];
+    }
+    this._callbacks[endpoint].push(callback);
+  };
+
  GrPluginEndpoints.prototype.registerModule = function(plugin, endpoint, type,
-      moduleName) {
+      moduleName, domHook) {
    if (!this._endpoints[endpoint]) {
      this._endpoints[endpoint] = [];
    }
-    this._endpoints[endpoint].push({
+    const moduleInfo = {
      moduleName,
      plugin,
      pluginUrl: plugin._url,
      type,
-    });
+      domHook,
+    };
+    this._endpoints[endpoint].push(moduleInfo);
+    if (Gerrit._arePluginsLoaded() && this._callbacks[endpoint]) {
+      this._callbacks[endpoint].forEach(callback => callback(moduleInfo));
+    }
  };

  /**
@ -44,6 +57,7 @@
   *   plugin: Plugin,
   *   pluginUrl: String,
   *   type: EndpointType,
+   *   domHook: !Object
   * }>}
   */
  GrPluginEndpoints.prototype.getDetails = function(name, opt_options) {
--- a/polygerrit-ui/app/elements/shared/gr-js-api-interface/gr-plugin-endpoints_test.html
+++ b/polygerrit-ui/app/elements/shared/gr-js-api-interface/gr-plugin-endpoints_test.html
@ -29,16 +29,21 @@ limitations under the License.
    let instance;
    let pluginFoo;
    let pluginBar;
+    let domHook;

    setup(() => {
      sandbox = sinon.sandbox.create();
+      domHook = {};
      instance = new GrPluginEndpoints();
      Gerrit.install(p => { pluginFoo = p; }, '0.1',
          'http://test.com/plugins/testplugin/static/foo.html');
-      instance.registerModule(pluginFoo, 'a-place', 'decorate', 'foo-module');
+      instance.registerModule(
+          pluginFoo, 'a-place', 'decorate', 'foo-module', domHook);
      Gerrit.install(p => { pluginBar = p; }, '0.1',
          'http://test.com/plugins/testplugin/static/bar.html');
-      instance.registerModule(pluginBar, 'a-place', 'style', 'bar-module');
+      instance.registerModule(
+          pluginBar, 'a-place', 'style', 'bar-module', domHook);
+      sandbox.stub(Gerrit, '_arePluginsLoaded').returns(true);
    });

    teardown(() => {
@ -52,12 +57,14 @@ limitations under the License.
          plugin: pluginFoo,
          pluginUrl: pluginFoo._url,
          type: 'decorate',
+          domHook,
        },
        {
          moduleName: 'bar-module',
          plugin: pluginBar,
          pluginUrl: pluginBar._url,
          type: 'style',
+          domHook,
        },
      ]);
    });
@ -69,6 +76,7 @@ limitations under the License.
          plugin: pluginBar,
          pluginUrl: pluginBar._url,
          type: 'style',
+          domHook,
        },
      ]);
    });
@ -82,6 +90,7 @@ limitations under the License.
              plugin: pluginFoo,
              pluginUrl: pluginFoo._url,
              type: 'decorate',
+              domHook,
            },
          ]);
    });
@ -95,5 +104,19 @@ limitations under the License.
      assert.deepEqual(
          instance.getPlugins('a-place'), [pluginFoo._url, pluginBar._url]);
    });
+
+    test('onNewEndpoint', () => {
+      const newModuleStub = sandbox.stub();
+      instance.onNewEndpoint('a-place', newModuleStub);
+      instance.registerModule(
+          pluginFoo, 'a-place', 'replace', 'zaz-module', domHook);
+      assert.deepEqual(newModuleStub.lastCall.args[0], {
+        moduleName: 'zaz-module',
+        plugin: pluginFoo,
+        pluginUrl: pluginFoo._url,
+        type: 'replace',
+        domHook,
+      });
+    });
  });
 </script>
--- a/polygerrit-ui/app/elements/shared/gr-js-api-interface/gr-public-js-api.js
+++ b/polygerrit-ui/app/elements/shared/gr-js-api-interface/gr-public-js-api.js
@ -55,8 +55,7 @@
  window.$wnd = window;

  function Plugin(opt_url) {
-    this._generatedHookNames = [];
-    this._domHooks = new GrDomHooks(this);
+    this._domHooks = new GrDomHooksManager(this);

    if (!opt_url) {
      console.warn('Plugin not being loaded from /plugins base path.',
@ -93,11 +92,22 @@
  };

  Plugin.prototype.registerCustomComponent = function(
-      endpointName, moduleName, opt_options) {
+      endpointName, opt_moduleName, opt_options) {
    const type = opt_options && opt_options.replace ?
          EndpointType.REPLACE : EndpointType.DECORATE;
+    const hook = this._domHooks.getDomHook(endpointName, opt_moduleName);
+    const moduleName = opt_moduleName || hook.getModuleName();
    Gerrit._endpoints.registerModule(
-        this, endpointName, type, moduleName);
+        this, endpointName, type, moduleName, hook);
+    return hook.getPublicAPI();
+  };
+
+  /**
+   * Returns instance of DOM hook API for endpoint. Creates a placeholder
+   * element for the first call.
+   */
+  Plugin.prototype.hook = function(endpointName, opt_options) {
+    return this.registerCustomComponent(endpointName, undefined, opt_options);
  };

  Plugin.prototype.getServerInfo = function() {
@ -166,14 +176,6 @@
    return new GrAttributeHelper(element);
  };

-  Plugin.prototype.getDomHook = function(endpointName, opt_options) {
-    const hook = this._domHooks.getDomHook(endpointName);
-    const moduleName = hook.getModuleName();
-    const type = opt_options && opt_options.type || EndpointType.DECORATE;
-    Gerrit._endpoints.registerModule(this, endpointName, type, moduleName);
-    return hook;
-  };
-
  const Gerrit = window.Gerrit || {};

  // Number of plugins to initialize, -1 means 'not yet known'.