cy.data() #2407

- Add impl.
- Add docs.
- Add basic tests.

documentation/docmaker.json

@@ -239,6 +239,63 @@
             {
               "name": "cy.destroyed",
               "descr": "Get whether the instance of Cytoscape.js has been destroyed or not."
+            }
+          ]
+        },
+
+        {
+          "name": "Data",
+
+          "fns": [
+            {
+              "name": "cy.data",
+              "pureAliases": [ "cy.attr" ],
+              "descr": "Read and write developer-defined data associated with the graph.",
+              "formatsSameFn": true,
+              "formats": [
+                {
+                  "name": "cy.data",
+                  "descr": "Get the entire data object."
+                },
+
+                {
+                  "name": "cy.data",
+                  "descr": "Get a particular data field.",
+                  "args": [ { "name": "name", "descr": "The name of the field to get." } ]
+                },
+
+                {
+                  "name": "cy.data",
+                  "descr": "Set a particular data field.",
+                  "args": [
+                    { "name": "name", "descr": "The name of the field to set." },
+                    { "name": "value", "descr": "The value to set for the field." }
+                  ]
+                },
+
+                {
+                  "name": "cy.data",
+                  "descr": "Update multiple data fields at once via an object.",
+                  "args": [
+                    { "name": "obj", "descr": "The object containing name-value pairs to update data fields." }
+                  ]
+                }
+              ]
+            },
+
+            {
+              "name": "cy.removeData",
+              "pureAliases": [ "cy.removeAttr" ],
+              "descr": "Remove developer-defined data associated with the elements.",
+              "formats": [
+                { "descr": "Removes all mutable data fields for the elements." },
+                {
+                  "descr": "Removes the specified mutable data fields for the elements.",
+                  "args": [
+                    { "name": "names", "descr": "A space-separated list of fields to delete." }
+                  ]
+                }
+              ]
             },
 
             {
@@ -861,6 +918,57 @@
               "descr": "Remove all queued animations for the viewport."
             }
           ]
+        },{
+          "name": "eles.data",
+          "pureAliases": [ "eles.attr" ],
+          "descr": "Read and write developer-defined data associated with the elements.",
+          "formatsSameFn": true,
+          "formats": [
+            {
+              "name": "ele.data",
+              "descr": "Get the entire data object."
+            },
+
+            {
+              "name": "ele.data",
+              "descr": "Get a particular data field for the element.",
+              "args": [ { "name": "name", "descr": "The name of the field to get." } ]
+            },
+
+            {
+              "name": "ele.data",
+              "descr": "Set a particular data field for the element.",
+              "args": [
+                { "name": "name", "descr": "The name of the field to set." },
+                { "name": "value", "descr": "The value to set for the field." }
+              ]
+            },
+
+            {
+              "name": "ele.data",
+              "descr": "Update multiple data fields at once via an object.",
+              "args": [
+                { "name": "obj", "descr": "The object containing name-value pairs to update data fields." }
+              ]
+            }
+          ],
+          "md": "collection/data"
+        },
+
+        {
+          "name": "eles.removeData",
+          "pureAliases": [ "eles.removeAttr" ],
+          "descr": "Remove developer-defined data associated with the elements.",
+          "formats": [
+            { "descr": "Removes all mutable data fields for the elements." },
+            {
+              "descr": "Removes the specified mutable data fields for the elements.",
+              "args": [
+                { "name": "names", "descr": "A space-separated list of fields to delete." }
+              ]
+            }
+          ],
+          "md": "collection/removeData"
         },
 
         {

src/core/data.js

@@ -0,0 +1,45 @@
+import define from '../define';
+
+const fn = {
+  data: define.data( {
+    field: 'data',
+    bindingEvent: 'data',
+    allowBinding: true,
+    allowSetting: true,
+    settingEvent: 'data',
+    settingTriggersEvent: true,
+    triggerFnName: 'trigger',
+    allowGetting: true
+  } ),
+
+  removeData: define.removeData( {
+    field: 'data',
+    event: 'data',
+    triggerFnName: 'trigger',
+    triggerEvent: true
+  } ),
+
+  scratch: define.data( {
+    field: 'scratch',
+    bindingEvent: 'scratch',
+    allowBinding: true,
+    allowSetting: true,
+    settingEvent: 'scratch',
+    settingTriggersEvent: true,
+    triggerFnName: 'trigger',
+    allowGetting: true
+  } ),
+
+  removeScratch: define.removeData( {
+    field: 'scratch',
+    event: 'scratch',
+    triggerFnName: 'trigger',
+    triggerEvent: true
+  } )
+};
+
+// aliases
+fn.attr = fn.data;
+fn.removeAttr = fn.removeData;
+
+export default fn;

src/core/index.js

@@ -3,7 +3,6 @@ import * as util from '../util';
 import Collection from '../collection';
 import * as is from '../is';
 import Promise from '../promise';
-import define from '../define';
 
 import addRemove from './add-remove';
 import animation from './animation';
@@ -15,6 +14,7 @@ import renderer from './renderer';
 import search from './search';
 import style from './style';
 import viewport from './viewport';
+import data from './data';
 
 let Core = function( opts ){
   let cy = this;
@@ -65,6 +65,7 @@ let Core = function( opts ){
     elements: new Collection( this ), // elements in the graph
     listeners: [], // list of listeners
     aniEles: new Collection( this ), // elements being animated
+    data: {}, // data for the core
     scratch: {}, // scratch object for core
     layout: null,
     renderer: null,
@@ -407,6 +408,10 @@ util.extend( corefn, {
         }
       }
 
+      if( obj.data ){
+        cy.data( obj.data );
+      }
+
       let fields = [
         'minZoom', 'maxZoom', 'zoomingEnabled', 'userZoomingEnabled',
         'panningEnabled', 'userPanningEnabled',
@@ -449,6 +454,8 @@ util.extend( corefn, {
         json.style = cy.style().json();
       }
 
+      json.data =  util.copy( cy.data() );
+
       let options = _p.options;
 
       json.zoomingEnabled = _p.zoomingEnabled;
@@ -468,25 +475,7 @@ util.extend( corefn, {
 
       return json;
     }
-  },
-
-  scratch: define.data( {
-    field: 'scratch',
-    bindingEvent: 'scratch',
-    allowBinding: true,
-    allowSetting: true,
-    settingEvent: 'scratch',
-    settingTriggersEvent: true,
-    triggerFnName: 'trigger',
-    allowGetting: true
-  } ),
-
-  removeScratch: define.removeData( {
-    field: 'scratch',
-    event: 'scratch',
-    triggerFnName: 'trigger',
-    triggerEvent: true
-  } )
+  }
 
 } );
 
@@ -503,6 +492,7 @@ corefn.$id = corefn.getElementById;
   search,
   style,
   viewport,
+  data
 ].forEach( function( props ){
   util.extend( corefn, props );
 } );

test/core-graph-manipulation.js

@@ -870,6 +870,29 @@ describe('Core graph manipulation', function(){
       expect( cy.userPanningEnabled() ).to.equal( true );
     });
 
+    it('cy.json() gets data', function(){
+      cy.data({ foo: 'bar' });
+
+      var json = cy.json();
+
+      expect(json.data.foo).to.equal('bar');
+    });
+
+    it('cy.json() sets data', function(){
+      cy.json({ data: { foo: 'bar' } });
+
+      expect(cy.data('foo')).to.equal('bar');
+    });
+  });
+
+  describe('cy.data()', function(){ // only basic test for now b/c shared impl w/ eles...
+    it('sets and gets data', function(){
+      cy.data({ foo: 'bar' });
+
+      expect(cy.data('foo')).to.equal('bar');
+    });
+
+    // TODO more tests in future
   });
 
   describe('cy.style()', function(){