Merge pull request #537 from Kitware/deprecate-get-plugin

Deprecate tangelo.getPlugin()
Kitware · Jan 21, 2016 · 4cf099a · 4cf099a
2 parents 733900b + 41e4002
commit 4cf099a
Show file tree

Hide file tree

Showing 12 changed files with 60 additions and 16 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,6 +12,7 @@ versioning](http://semver.org).
 - Quiet option reduces verbosity
 - "Watch" plugin controls whether services and dependent modules are
   automatically reloaded when they change
+- ``tangelo.ensurePlugin()`` function that avoids JavaScript parsing problems
 
 ### Changed
 - Documentation introduction is more focused; tutorials are more
@@ -26,6 +27,7 @@ versioning](http://semver.org).
 - Bundled Mongo plugin updated to use PyMongo 3.2
 
 ### Deprecated
+- ``tangelo.getPlugin()`` - use ``tangelo.ensurePlugin()`` instead
 
 ### Removed
 - "System Architecture" section in README

diff --git a/docs/tangelo-js.rst b/docs/tangelo-js.rst
@@ -15,8 +15,35 @@ functions, see :ref:`bundled`.
     Returns a string representing Tangelo's current version number.  See
     :ref:`versioning` for more information on Tangelo version numbers.
 
+.. js:function:: tangelo.ensurePlugin(pluginName)
+
+    :param pluginName string: The name of the plugin whose existence to ensure
+
+    Creates a Tangelo plugin namespace for `pluginName`, if it does not yet
+    exist. If it already exists, this function does nothing.
+
+    This is the standard way to ensure that a plugin has been created. For
+    instead, if ``foobar.js`` introduces the *foobar* clientside plugin, it may
+    contain code like this:
+
+    .. code-block:: javascript
+
+        tangelo.ensurePlugin("foobar");
+
+        var plugin = tangelo.plugin.foobar;
+
+        plugin.awesomeFunction = function () { ... };
+        plugin.greatConstant = ...;
+
+    As demonstrated here, once the existence of plugin *foobar* is guaranteed by
+    the call to :js:func:`tangelo.ensurePlugin()`, it can thereafter be
+    referenced by the name ``tangelo.plugin.foobar``.
+
 .. js:function:: tangelo.getPlugin(pluginName)
 
+    .. deprecated:: 0.10
+        See :js:func:`tangelo.ensurePlugin` for the replacement.
+
     :param pluginName string: The name of the plugin to retrieve
 
     :rtype: **object** -- the contents of the requested plugin

diff --git a/js/src/core.js b/js/src/core.js
@@ -13,6 +13,13 @@ window.tangelo = {};
     // A namespace for plugins.
     tangelo.plugin = {};
 
+    // Create a plugin namespace if it does not exist; otherwise, do nothing.
+    tangelo.ensurePlugin = function (plugin) {
+        if (tangelo.plugin[plugin] === undefined) {
+            tangelo.plugin[plugin] = {};
+        }
+    };
+
     // Standard way to access a plugin namespace.
     tangelo.getPlugin = function (plugin) {
         if (tangelo.plugin[plugin] === undefined) {

diff --git a/js/tests/plugin.js b/js/tests/plugin.js
@@ -1,26 +1,25 @@
 QUnit.module("Tangelo plugins");
 
-QUnit.test("tangelo.getPlugin()", function (assert) {
+QUnit.test("tangelo.ensurePlugin()", function (assert) {
     "use strict";
 
-    var plugin,
-        slogan,
-        plugin2;
+    var slogan;
 
-    plugin = tangelo.getPlugin("slugocola");
+    tangelo.ensurePlugin("slugocola");
     assert.deepEqual(tangelo.plugin.slugocola, {}, "A freshly created plugin should be installed to the tangelo plugin namespace and be empty");
 
     slogan = "Drink Slug-o-Cola! The slimiest cola in the galaxy!";
-    plugin.slogan = slogan;
+    tangelo.plugin.slugocola.slogan = slogan;
     assert.strictEqual(tangelo.plugin.slugocola.slogan, slogan, "Using the plugin object shoould affect the actual plugin namespace");
 
     tangelo.plugin.slugocola.add = function (a, b) {
         return a + b;
     };
     assert.strictEqual(tangelo.plugin.slugocola.add(3, 4), 7, "Functions installed in the plugin should work as expected");
 
-    plugin2 = tangelo.getPlugin("slugocola");
-    assert.strictEqual(plugin, plugin2, "Using getPlugin() on an existing plugin should return a reference to the plugin");
+    tangelo.ensurePlugin("slugocola");
+    assert.strictEqual(tangelo.plugin.slugocola.slogan, slogan, "tangelo.ensurePlugin() is idempotent - 1");
+    assert.strictEqual(tangelo.plugin.slugocola.add(3, 4), 7, "tangelo.ensurePlugin() is idempotent - 2");
 });
 
 QUnit.test("tangelo.pluginUrl()", function (assert) {

diff --git a/tangelo/tangelo/pkgdata/plugin/config/web/config.js b/tangelo/tangelo/pkgdata/plugin/config/web/config.js
@@ -7,7 +7,9 @@
 (function (tangelo, _, $) {
     "use strict";
 
-    tangelo.getPlugin("config").config = function (url, required, callback) {
+    tangelo.ensurePlugin("config");
+
+    tangelo.plugin.config.config = function (url, required, callback) {
         if (url === undefined) {
             throw new Error("'url' parameter is required");
         }

diff --git a/tangelo/tangelo/pkgdata/plugin/data/web/bin.js b/tangelo/tangelo/pkgdata/plugin/data/web/bin.js
@@ -1,7 +1,8 @@
 (function (tangelo) {
     "use strict";
 
-    var dataPlugin = tangelo.getPlugin("data");
+    tangelo.ensurePlugin("data");
+    var dataPlugin = tangelo.plugin.data;
 
     function makeBins(data, value, minArg, maxArg, nBins) {
         var min = Number.POSITIVE_INFINITY,

diff --git a/tangelo/tangelo/pkgdata/plugin/data/web/distanceCluster.js b/tangelo/tangelo/pkgdata/plugin/data/web/distanceCluster.js
@@ -50,7 +50,8 @@
 (function (tangelo, _) {
     "use strict";
 
-    var dataPlugin = tangelo.getPlugin("data");
+    tangelo.ensurePlugin("data");
+    var dataPlugin = tangelo.plugin.data;
 
     // default metric: 2D euclidean metric
     function defaultMetric(xAcc, yAcc) {

diff --git a/tangelo/tangelo/pkgdata/plugin/data/web/smooth.js b/tangelo/tangelo/pkgdata/plugin/data/web/smooth.js
@@ -40,7 +40,8 @@
     var dataPlugin,
         kernels;
 
-    dataPlugin = tangelo.getPlugin("data");
+    tangelo.ensurePlugin("data");
+    dataPlugin = tangelo.plugin.data;
 
     // predefined kernels
     kernels = {

diff --git a/tangelo/tangelo/pkgdata/plugin/data/web/tree.js b/tangelo/tangelo/pkgdata/plugin/data/web/tree.js
@@ -1,7 +1,8 @@
 (function (tangelo) {
     "use strict";
 
-    var dataPlugin = tangelo.getPlugin("data");
+    tangelo.ensurePlugin("data");
+    var dataPlugin = tangelo.plugin.data;
 
     dataPlugin.tree = function (spec) {
         var id = tangelo.accessor(spec.id || {value: ""}),

diff --git a/tangelo/tangelo/pkgdata/plugin/mapping/web/geovis.js b/tangelo/tangelo/pkgdata/plugin/mapping/web/geovis.js
@@ -1,7 +1,8 @@
 (function (tangelo) {
     "use strict";
 
-    var mapping = tangelo.getPlugin("mapping");
+    tangelo.ensurePlugin("mapping");
+    var mapping = tangelo.plugin.mapping;
 
     mapping.geovis = function (worldGeometryFile) {
         var spec = {

diff --git a/tangelo/tangelo/pkgdata/plugin/stream/web/stream.js b/tangelo/tangelo/pkgdata/plugin/stream/web/stream.js
@@ -1,7 +1,8 @@
 (function (tangelo, $, _) {
     "use strict";
 
-    var streamPlugin = tangelo.getPlugin("stream");
+    tangelo.ensurePlugin("stream");
+    var streamPlugin = tangelo.plugin.stream;
 
     streamPlugin.streams = function (callback) {
         $.ajax({

diff --git a/tangelo/tangelo/pkgdata/plugin/vtkweb/web/vtkweb.js b/tangelo/tangelo/pkgdata/plugin/vtkweb/web/vtkweb.js
@@ -3,7 +3,8 @@
 (function (tangelo, $, vtkWeb) {
     "use strict";
 
-    var plugin = tangelo.getPlugin("vtkweb");
+    tangelo.ensurePlugin("vtkweb");
+    var plugin = tangelo.plugin.vtkweb;
 
     plugin.processes = function (callback) {
         $.ajax({