rework bulk cell saving and updating formulas!

.gitignore

@@ -1,3 +1,4 @@
 node_modules/
 ignore/
-.env
+.env
+test.js

README.md

@@ -192,6 +192,7 @@ Add a single row to the sheet.
 #### `GoogleSpreadsheet.getCells(worksheet_id, options, callback)`
 
 Get an array of cell objects.
+
 - `worksheet_id` - the index of the sheet to add to (index starts at 1)
 - `options` (optional)
   - `min-row` - row range min (uses #s visible on the left)
@@ -200,6 +201,27 @@ Get an array of cell objects.
   - `max-col` - column range max
   - `return-empty` - include empty cells (boolean)
 
+#### `GoogleSpreadsheet.bulkUpdateCells(worksheet_id, cells, callback)`
+
+Do a bulk update on cells.
+
+- `worksheet_id` - the index of the sheet to add to (index starts at 1)
+- `cells` - an array of SpreadsheetCell objects to save
+
+#### `GoogleSpreadsheet.addWorksheet(options, callback)`
+
+Add a new worksheet to the doc.
+
+- `options` (optional)
+  - `title` - title for the new sheet (default = 'New Worksheet')
+  - `rowCount` - number of rows (default = 50)
+  - `colCount` - number of columns (default = 10)
+
+#### `GoogleSpreadsheet.deleteWorksheet(worksheet_id, callback)`
+
+Remove a worksheet from the doc.
+
+- `worksheet_id` - the index of the sheet to add to (index starts at 1)
 
 ----------------------------------
 
@@ -210,6 +232,7 @@ Represents a single "sheet" from the spreadsheet. These are the different tabs/p
 This is a really just a wrapper to call the same functions on the spreadsheet without needing to include the worksheet id.
 
 __Properties:__
+- `url` - the URL for the sheet
 - `id` - the ID of the sheet
 - `title` - the title (visible on the tabs in google's interface)
 - `rowCount` - number of rows
@@ -224,6 +247,12 @@ See above.
 ### `SpreadsheetWorksheet.addRow(new_row, callback)`
 See above.
 
+#### `SpreadsheetWorksheet.bulkUpdateCells(cells, callback)`
+See above.
+
+### `SpreadsheetWorksheet.del(callback)`
+Remove this sheet from the doc.
+
 ----------------------------------
 
 ### `SpreadsheetRow`
@@ -241,9 +270,25 @@ Deletes the row from the sheet.
 
 ### `SpreadsheetCell`
 Represents a single cell from the sheet.
+Using cells is the only way to read and modify the formulas in your sheet.
+
+__Properties:__
+- `id` - the ID of the cell
+- `row` - the row this cell is in
+- `col` - the column this cell is in
+- `value` - the value of the cell
+- `numericValue` - the value of the cell as a number
+- `inputValue` - the "raw" value of the cell which can be a formula
+
+__IMPORTANT__:
+- Cells with regular values can be modified by setting `value` and calling `save`
+- Cells with formulas in them can be modified by setting `inputValue` and calling `save`
 
 #### `SpreadsheetCell.setValue(val, callback)`
-Set the value of the cell and save it.
+Set the value of the cell and saves it.
+
+#### `SpreadsheetCell.save(callback)`
+Saves the current value/formula
 
 #### `SpreadsheetCell.del(callback)`
 Clear the cell -- internally just calls `.setValue('', callback)`

index.js

@@ -271,15 +271,16 @@ var GooogleSpreadsheet = function( ss_key, auth_id, options ){
     });
   }
 
-  // this.bulkUpdateCells = function (worksheet_id, cells, values, cb) {
+  // this.bulkUpdateCells = function (worksheet_id, cells, cb) {
   //   var entries = cells.map((cell, i) => {
+  //     cell._needsSave = false;
   //     return `<entry>
   //       <batch:id>${cell.id}</batch:id>
   //       <batch:operation type="update"/>
   //       <id>${cell.id}</id>
   //       <link rel="edit" type="application/atom+xml"
   //         href="${cell._links.edit}"/>
-  //       <gs:cell row="${cell.row}" col="${cell.col}" inputValue="${(values[i] || '')}"/>
+  //       <gs:cell row="${cell.row}" col="${cell.col}" inputValue="${cell.getValueForSave()}"/>
   //     </entry>`
   //   });
   //   var worksheetUrl = `https://spreadsheets.google.com/feeds/cells/${ss_key}/${worksheet_id}/private/full`;
@@ -294,9 +295,10 @@ var GooogleSpreadsheet = function( ss_key, auth_id, options ){
   //                        'POST', data_xml, cb)
   // }
 
-  this.bulkUpdateCells = function (worksheet_id, cells, values, cb) {
+  this.bulkUpdateCells = function (worksheet_id, cells, cb) {
     var entries = cells.map(function (cell, i) {
-      return "<entry>\n        <batch:id>" + cell.id + "</batch:id>\n        <batch:operation type=\"update\"/>\n        <id>" + cell.id + "</id>\n        <link rel=\"edit\" type=\"application/atom+xml\"\n          href=\"" + cell._links.edit + "\"/>\n        <gs:cell row=\"" + cell.row + "\" col=\"" + cell.col + "\" inputValue=\"" + (values[i] || '') + "\"/>\n      </entry>";
+      cell._needsSave = false;
+      return "<entry>\n        <batch:id>" + cell.id + "</batch:id>\n        <batch:operation type=\"update\"/>\n        <id>" + cell.id + "</id>\n        <link rel=\"edit\" type=\"application/atom+xml\"\n          href=\"" + cell._links.edit + "\"/>\n        <gs:cell row=\"" + cell.row + "\" col=\"" + cell.col + "\" inputValue=\"" + cell.getValueForSave() + "\"/>\n      </entry>";
     });
     var worksheetUrl = "https://spreadsheets.google.com/feeds/cells/" + ss_key + "/" + worksheet_id + "/private/full";
     var data_xml = "<feed xmlns=\"http://www.w3.org/2005/Atom\"\n      xmlns:batch=\"http://schemas.google.com/gdata/batch\"\n      xmlns:gs=\"http://schemas.google.com/spreadsheets/2006\">\n      <id>" + worksheetUrl + "</id>\n      " + entries.join("\n") + "\n    </feed>";
@@ -323,6 +325,9 @@ var SpreadsheetWorksheet = function( spreadsheet, data ){
   this.addRow = function( data, cb ){
     spreadsheet.addRow( self.id, data, cb );
   }
+  this.bulkUpdateCells = function( cells, cb ) {
+    spreadsheet.bulkUpdateCells( self.id, cells, cb );
+  }
   this.del = function ( cb ){
     spreadsheet.makeFeedRequest( self.url, 'DELETE', null, cb );
   }
@@ -389,24 +394,35 @@ var SpreadsheetCell = function( spreadsheet, worksheet_id, data ){
   self.numericValue = data['gs:cell']['$']['numericValue'];
   self.inputValue = data['gs:cell']['$']['inputValue'];
 
+  var _hasFormula = self.inputValue.substr(0,1) === '=';
+
   self['_links'] = [];
   links = forceArray( data.link );
   links.forEach( function( link ){
     self['_links'][ link['$']['rel'] ] = link['$']['href'];
   });
 
+  self.getValueForSave = function(){
+    if (_hasFormula){
+      return self.inputValue;
+    } else {
+      return xmlSafeValue(self.value);
+    }
+  }
+
   self.setValue = function(new_value, cb) {
     self.value = new_value;
     self.save(cb);
   };
 
   self.save = function(cb) {
-    new_value = xmlSafeValue(self.value);
+    self._needsSave = false;
+
     var edit_id = 'https://spreadsheets.google.com/feeds/cells/key/worksheetId/private/full/R'+self.row+'C'+self.col;
     var data_xml =
     '<entry><id>'+edit_id+'</id>'+
     '<link rel="edit" type="application/atom+xml" href="'+edit_id+'"/>'+
-    '<gs:cell row="'+self.row+'" col="'+self.col+'" inputValue="'+new_value+'"/></entry>'
+    '<gs:cell row="'+self.row+'" col="'+self.col+'" inputValue="'+self.getValueForSave()+'"/></entry>'
 
     data_xml = data_xml.replace('<entry>', "<entry xmlns='http://www.w3.org/2005/Atom' xmlns:gs='http://schemas.google.com/spreadsheets/2006'>");