Refactoring re. build system and events cytoscape#1685 cytoscape#1823

- Babel support - Use lodash.debounce - Allow single object to specify Event; Only do `new Event()` in a couple places so potentially pooling could be used in future - Use .emit() and .removeListener() by default - .rtrigger() => .emitAndNotify() - .trigger() => .emit() - Removes old define code for events and adds generic Emitter - Splits up defines and allows for external deps
MDZforever · May 17, 2017 · c9bb72c · c9bb72c
1 parent c5c9f80
commit c9bb72c
Show file tree

Hide file tree

Showing 112 changed files with 3,655 additions and 3,857 deletions.
diff --git a/.babelrc b/.babelrc
@@ -0,0 +1,3 @@
+{
+  "presets": ["es2015"]
+}
diff --git a/.eslintrc.json b/.eslintrc.json
@@ -5,7 +5,7 @@
         "mocha": true
     },
     "parserOptions": {
-      "ecmaVersion": 5
+      "ecmaVersion": 6
     },
     "extends": "eslint:recommended",
     "rules": {

diff --git a/.travis.yml b/.travis.yml
@@ -9,3 +9,4 @@ node_js:
   - "7"
   - "stable"
 sudo: false
+script: npm run test-travis
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -2,6 +2,8 @@
 
 Cytoscape.js is an open source project, and we greatly appreciate any and all contributions.
 
+Cytoscape.js is transpiled with Babel, so ES2015/ES6 language features can be used.
+
 If you'd like to contribute code to Cytoscape.js but you're not sure exactly what you'd like to implement, take a look at our [current milestones](https://github.com/cytoscape/cytoscape.js/milestones) to see what features we have planned in future --- or anything labelled [`help-wanted`](https://github.com/cytoscape/cytoscape.js/issues?q=is%3Aopen+is%3Aissue+label%3Ahelp-wanted).  Of course, we also welcome your own ideas.
 
 Our goal is to make Cytoscape.js as comprehensive as possible.  Thank you for taking the time and effort to contribute to help make that happen!

diff --git a/README.md b/README.md
@@ -78,12 +78,15 @@ Run `gulp <target>` in the console.  The main targets are:
 
  * `build` (default) : build the library
  * `clean` : clean the `build` directory
- * `watch` : automatically build lib and tests for debugging
+ * `watch` : automatically build lib and tests for debugging (no babel)
+ * `watch-babel` : automatically build lib and tests for debugging (with babel; good for testing out of date browsers)
  * `zip` : build the release ZIP
  * `dist` : update the distribution JS for npm, bower, etc.
 
 **Testing:**
 
+If the `TRAVIS` or `TEST_BUILD` environment variables are defined, then `mocha` or `gulp test` will test `build/cytoscape.cjs.js`.  Otherwise, the unbundled, unbabelified, raw source is tested.  This keeps local tests very quick to run on modern versions of Node while ensuring we can test old versions of Node as well.
+
  * `test` : run the Mocha unit tests
  * `lint` : lint the JS sources via eslint
  * `benchmark` : run benchmark regression tests

diff --git a/documentation/docmaker.json b/documentation/docmaker.json
@@ -267,7 +267,7 @@
                 {
                   "args": [
                     { "name": "events", "descr": "A space separated list of event names." },
-                    { "name": "selector", "descr": "A selector to specify elements for which the handler is triggered.", "optional": true },
+                    { "name": "selector", "descr": "A selector to specify elements for which the handler is ran.", "optional": true },
                     { "name": "function(event)", "descr": "The handler function that is called when one of the specified events occurs.", "fields": [ { "name": "event", "descr": "The event object." } ] }
                   ]
                 }
@@ -278,12 +278,12 @@
             {
               "name": "cy.promiseOn",
               "pureAliases": ["cy.pon"],
-              "descr": "Get a promise that is resolved with the first of any of the specified events triggered on the graph.",
+              "descr": "Get a promise that is resolved with the first of any of the specified events emitted on the graph.",
               "formats": [
                 {
                   "args": [
                     { "name": "events", "descr": "A space separated list of event names." },
-                    { "name": "selector", "descr": "A selector to specify elements for which the handler is triggered.", "optional": true }
+                    { "name": "selector", "descr": "A selector to specify elements for which the handler is ran.", "optional": true }
                   ]
                 }
               ],
@@ -292,12 +292,12 @@
 
             {
               "name": "cy.one",
-              "descr": "Bind to events that occur in the graph, and trigger the handler only once.",
+              "descr": "Bind to events that occur in the graph, and run the handler only once.",
               "formats": [
                 {
                   "args": [
                     { "name": "events", "descr": "A space separated list of event names." },
-                    { "name": "selector", "descr": "A selector to specify elements for which the handler is triggered.", "optional": true },
+                    { "name": "selector", "descr": "A selector to specify elements for which the handler is ran.", "optional": true },
                     { "name": "function(event)", "descr": "The handler function that is called when one of the specified events occurs.", "fields": [ { "name": "event", "descr": "The event object." } ] }
                   ]
                 }
@@ -306,8 +306,8 @@
             },
 
             {
-              "name": "cy.off",
-              "pureAliases": ["cy.unbind", "cy.unlisten", "cy.removeListener"],
+              "name": "cy.removeListener",
+              "pureAliases": ["cy.off", "cy.unbind", "cy.unlisten"],
               "descr": "Remove event handlers.",
               "formats": [
                 {
@@ -318,22 +318,22 @@
                   ]
                 }
               ],
-              "md": "core/off"
+              "md": "core/removeListener"
             },
 
             {
-              "name": "cy.trigger",
-              "pureAliases": ["cy.emit"],
-              "descr": "Trigger one or more events.",
+              "name": "cy.emit",
+              "pureAliases": ["cy.trigger"],
+              "descr": "Emit one or more events.",
               "formats": [
                 {
                   "args": [
-                    { "name": "events", "descr": "A space separated list of event names to trigger." },
+                    { "name": "events", "descr": "A space separated list of event names to emit." },
                     { "name": "extraParams", "descr": "An array of additional parameters to pass to the handler.", "optional": true }
                   ]
                 }
               ],
-              "md": "core/trigger"
+              "md": "core/emit"
             },
 
             {
@@ -1007,7 +1007,7 @@
                 {
                   "args": [
                     { "name": "events", "descr": "A space separated list of event names." },
-                    { "name": "selector", "descr": "A delegate selector to specify child elements for which the handler is triggered.", "optional": true },
+                    { "name": "selector", "descr": "A delegate selector to specify child elements for which the handler is ran.", "optional": true },
                     { "name": "function(event)", "descr": "The handler function that is called when one of the specified events occurs.", "fields": [ { "name": "event", "descr": "The event object." } ] }
                   ]
                 }
@@ -1018,12 +1018,12 @@
             {
               "name": "eles.promiseOn",
               "pureAliases": ["eles.pon"],
-              "descr": "Get a promise that is resolved with the first of any of the specified events triggered on any of the elements in the collection.",
+              "descr": "Get a promise that is resolved with the first of any of the specified events emitted on any of the elements in the collection.",
               "formats": [
                 {
                   "args": [
                     { "name": "events", "descr": "A space separated list of event names." },
-                    { "name": "selector", "descr": "A selector to specify elements for which the handler is triggered.", "optional": true }
+                    { "name": "selector", "descr": "A selector to specify elements for which the handler is emitted.", "optional": true }
                   ]
                 }
               ],
@@ -1032,12 +1032,12 @@
 
             {
               "name": "eles.one",
-              "descr": "Bind a callback function that is triggered once per event per element.",
+              "descr": "Bind a callback function that is emitted once per event per element.",
               "formats": [
                 {
                   "args": [
                     { "name": "events", "descr": "A space separated list of event names." },
-                    { "name": "selector", "descr": "A delegate selector to specify child elements for which the handler is triggered.", "optional": true },
+                    { "name": "selector", "descr": "A delegate selector to specify child elements for which the handler is ran.", "optional": true },
                     { "name": "function(event)", "descr": "The handler function that is called when one of the specified events occurs.", "fields": [ { "name": "event", "descr": "The event object." } ] }
                   ]
                 }
@@ -1047,12 +1047,12 @@
 
             {
               "name": "eles.once",
-              "descr": "Bind a callback function that is triggered once per event per collection.",
+              "descr": "Bind a callback function that is emitted once per event per collection.",
               "formats": [
                 {
                   "args": [
                     { "name": "events", "descr": "A space separated list of event names." },
-                    { "name": "selector", "descr": "A delegate selector to specify child elements for which the handler is triggered.", "optional": true },
+                    { "name": "selector", "descr": "A delegate selector to specify child elements for which the handler is ran.", "optional": true },
                     { "name": "function(event)", "descr": "The handler function that is called when one of the specified events occurs.", "fields": [ { "name": "event", "descr": "The event object." } ] }
                   ]
                 }
@@ -1061,8 +1061,8 @@
             },
 
             {
-              "name": "eles.off",
-              "pureAliases": ["eles.unbind", "eles.unlisten", "eles.removeListener"],
+              "name": "eles.removeListener",
+              "pureAliases": ["eles.off", "eles.unbind", "eles.unlisten"],
               "descr": "Unbind one or more callback functions on the elements.",
               "formats": [
                 {
@@ -1073,22 +1073,22 @@
                   ]
                 }
               ],
-              "md": "collection/off"
+              "md": "collection/removeListener"
             },
 
             {
-              "name": "eles.trigger",
-              "pureAliases": ["eles.emit"],
-              "descr": "Trigger events on the elements.",
+              "name": "eles.emit",
+              "pureAliases": ["eles.trigger"],
+              "descr": "Emit events on the elements.",
               "formats": [
                 {
                   "args": [
-                    { "name": "events", "descr": "A space separated list of event names to trigger." },
+                    { "name": "events", "descr": "A space separated list of event names to emit." },
                     { "name": "extraParams", "descr": "An array of additional parameters to pass to the handler.", "optional": true }
                   ]
                 }
               ],
-              "md": "collection/trigger"
+              "md": "collection/emit"
             }
           ]
         },
@@ -3193,7 +3193,7 @@
             {
               "name": "layout.promiseOn",
               "pureAliases": ["layout.pon"],
-              "descr": "Get a promise that is resolved with the first of any of the specified events triggered on the layout.",
+              "descr": "Get a promise that is resolved with the first of any of the specified events emitted on the layout.",
               "formats": [
                 {
                   "args": [
@@ -3206,7 +3206,7 @@
 
             {
               "name": "layout.one",
-              "descr": "Bind to events that are emitted by the layout, and trigger the handler only once.",
+              "descr": "Bind to events that are emitted by the layout, and run the handler only once.",
               "formats": [
                 {
                   "args": [
@@ -3220,8 +3220,8 @@
             },
 
             {
-              "name": "layout.off",
-              "pureAliases": ["layout.unbind", "layout.unlisten", "layout.removeListener"],
+              "name": "layout.removeListener",
+              "pureAliases": ["layout.off", "layout.unbind", "layout.unlisten"],
               "descr": "Remove event handlers on the layout.",
               "formats": [
                 {
@@ -3231,22 +3231,22 @@
                   ]
                 }
               ],
-              "md": "layout/off"
+              "md": "layout/removeListener"
             },
 
             {
-              "name": "layout.trigger",
-              "pureAliases": ["layout.emit"],
-              "descr": "Trigger one or more events on the layout.",
+              "name": "layout.emit",
+              "pureAliases": ["layout.trigger"],
+              "descr": "Emit one or more events on the layout.",
               "formats": [
                 {
                   "args": [
-                    { "name": "events", "descr": "A space separated list of event names to trigger." },
+                    { "name": "events", "descr": "A space separated list of event names to emit." },
                     { "name": "extraParams", "descr": "An array of additional parameters to pass to the handler.", "optional": true }
                   ]
                 }
               ],
-              "md": "layout/trigger"
+              "md": "layout/emit"
             }
           ]
         }

diff --git a/documentation/md/collection/trigger.md → documentation/md/collection/emit.md b/documentation/md/collection/trigger.md → documentation/md/collection/emit.md
@@ -7,5 +7,5 @@ j.on('tap', function(){
   console.log('tap!!');
 });
 
-j.trigger('tap'); // tap!!
-```
+j.emit('tap'); // tap!!
+```
diff --git a/documentation/md/collection/off.md → ...mentation/md/collection/removeListener.md b/documentation/md/collection/off.md → ...mentation/md/collection/removeListener.md
@@ -12,13 +12,13 @@ j.on('tap', function(){
   console.log('some other handler');
 });
 
-j.trigger('tap'); // 'tap' & 'some other handler'
+j.emit('tap'); // 'tap' & 'some other handler'
 
 // unbind the renferenced handler
-j.off('tap', handler);
+j.removeListener('tap', handler);
 
-j.trigger('tap'); // some other handler
+j.emit('tap'); // some other handler
 
 // unbind all tap handlers (including unnamed handler)
-j.off('tap');
-```
+j.removeListener('tap');
+```
diff --git a/documentation/md/core/emit.md b/documentation/md/core/emit.md
@@ -0,0 +1,9 @@
+## Examples
+
+```js
+cy.on('tap', function(evt, f, b){
+  console.log('tap', f, b);
+});
+
+cy.emit('tap', ['foo', 'bar']);
+```
diff --git a/documentation/md/core/off.md b/documentation/md/core/off.md
diff --git a/documentation/md/core/removeListener.md b/documentation/md/core/removeListener.md
@@ -0,0 +1,27 @@
+## Examples
+
+For all handlers:
+
+```js
+cy.on('tap', function(){ /* ... */ });
+
+// unbind all tap handlers, including the one above
+cy.removeListener('tap');
+```
+
+For a particular handler:
+
+```js
+var handler = function(){
+  console.log('called handler');
+};
+cy.on('tap', handler);
+
+var otherHandler = function(){
+  console.log('called other handler');
+};
+cy.on('tap', otherHandler);
+
+// just unbind handler
+cy.removeListener('tap', handler);
+```
diff --git a/documentation/md/core/trigger.md b/documentation/md/core/trigger.md
diff --git a/documentation/md/intro.md b/documentation/md/intro.md
@@ -4,7 +4,6 @@
  * Permissive open source license (MIT)
  * Designed for users first, for both frontfacing app usercases *and* developer usecases
  * Highly optimised
- * Dependency free
  * Compatible with
   * All modern browsers
   * CommonJS/Node.js

diff --git a/documentation/md/layout/trigger.md → documentation/md/layout/emit.md b/documentation/md/layout/trigger.md → documentation/md/layout/emit.md