Angular-gcms

Mock a read-only backend easily

Angular is awesome, but one of the biggest hurdles in prototyping a new project is getting together a backend service to build off of. I often found myself in situations where I wanted an easily modified backend, ideally one that non-technical co-workers could modify (i.e. "do the data entry for").

There's actually a great data modeling service that allows easy collaborative editing: Google Spreadsheets. And awesomely enough, it has a JSON interface where you can grab the spreadsheet as a JSON blob. The formatting is a bit wonky, which is where angular-gcms comes in.

For read-only backends or prototyping, this is a great solution. If you want to write as well, you could always wrap together a service that reads from the spreadsheet, saves a version in localStorage, and then writes to that cached version (as long as data synchronization between clients was not necessary).

How to use

Installation

To install, just use bower:

$ bower install jlovison/angular-gcms

After linking the resulting javascript file into your project's HTML (a minified version can be found in the 'dist' directory), add the project module as a dependency to your angular project module declaration:

angular.module('YourModule', ['OtherStuff', 'jlovison.gcms'])

Setting up a Google Spreadsheet

Now you need a Google Spreadsheet modeled around your data. Create a spreadsheet on Google Drive. The top row will be ignored, so feel free to add in column headers for the data, along with some initial data values.

Ok, great. Now, to make the spreadsheet accessible for ingestion with the GcmsService, go to File > Publish to the web. You'll see various options regarding how the document is published, but it doesn't matter what you select, as long as the document is published. While here though, make sure to copy down the spreadsheet ID (you can find it in the url for the 'Document link' -- it's the long number between /d/ and /pubhtml).

That's all for the spreadsheet.

Using the GcmsService in your project

So now let's fetch the data in your spreadsheet into your project. I'll illustrate a simple controller use case (where you want to map the data into a variable bound to your scope). You could also use this service within other services, etc.

Inside your controller.js:

angular.module('YourApp')
  .controller('YourController', function ($scope, GcmsService) {
    // Fetch the content
    GcmsService.get(
      '0123456789ABCDEFGHIJKLMNOPQRSTUVWZYZ11121314', // Your spreadsheet ID 
      ['fieldName1', 'fieldName2']  // Your column names (in correct order)
    ).then(function(data) {
      $scope.content = data; 
    });
  });

The service takes your spreadsheet ID and a list of your column names, and returns a promise, which, once it resolves, has a data object that has each row as an object with attributes that match your column names, and values matching the respective data in the spreadsheet.

Caveats

Sometimes I've had strange results with the Google Spreadsheet JSON interface when the table cells include apostrophes. In general, know that the entire service could easily break should Google make any changes to how Spreadsheet documents are presented as JSON. So while this is a really useful resource in quickly developing a prototype or demo, I REALLY don't suggest using it in production (or at least for anything critical).

Contributing

Feel free to issue pull requests (with tests if major changes/additions). Though I've kept the scope of the project somewhat limited, this is more a reflection of my needs so far in using it, and not necessarily a desire to avoid features if a good fit.