grunt-gss
Version:
Save your Google Spreadsheets as CSV or JSON.
166 lines (142 loc) • 6.38 kB
Markdown
# grunt-gss v1.0.4
> Save your Google Spreadsheets as CSV or JSON.
## Getting Started
This plugin requires Grunt `~0.4.0`
If you haven't used [Grunt](http://gruntjs.com/) before, be sure to check out the [Getting Started](http://gruntjs.com/getting-started) guide, as it explains how to create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
```shell
npm install grunt-gss --save-dev
```
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
```js
grunt.loadNpmTasks('grunt-gss');
```
### Overview
Google Spreadsheet could be a simple yet powerful front end for average users to preform management to loads of JSON files.
A handy tool for [CouchDB](http://couchdb.apache.org/#download)-backed apps like [couch-web](https://github.com/h0ward/couch-web).
### Setup API key
1. Go to [API Console](https://code.google.com/apis/console) and create a project
* Turn on **Drive API** in **APIS**
* **Create new client ID** in **Credentials** and setup accordingly:
Application type: **Web application**
Authorized Javascript origins: **http://localhost/**
Authorized redirect URI: **http://localhost:4477/**
* Under **Consent screen**, set **Email address** and **Product name**
* After the ID is created, you will see your `clientId` and `clientSecret`
### Share spreadsheet
1. Check out demo file [here](https://docs.google.com/spreadsheet/ccc?key=0AmPyOqJNrt_SdGlZOVlrc2UzS3FpV1V6Ri1jX0haSlE#gid=1#gid=1).
2. `key` and `gid` could be found in the URL of your spreadsheet
3. Do it as usual under **File > Share**
4. Without proper permission set, you will get a **File not found** error from Google
### Task Options
1. `clientId` and `clientSecret` are from your Google API key
* `json` set true to save as JSON, otherwise raw CSV is saved
* `prettify` works for JSON format only, 2 spaces indention
* ~~typeDetection apply one of these: parseInt, parseFloat, or split(',')~~ `Removed since v1.0.0`
* `mapping` an object containing `col:type` mappings. Possible types are:
* array - `split(",")`
* number - `parseFloat`
* string - `toString()`
* undefined - `delete row[col]`
* or a callback function accepting `(val, row)` and returning whatever can be parsed by `JSON.parse`
* `wrap` output string will be passed to this callback and the return will be saved
~~*Note 1: If both typeDetection and typeMapping are true, typeDetection will be executed first, and followed by typeMapping overriding the outcome. That is, value passing totypeMapping callback may not be string.*~~ `Removed since v1.0.0`
~~*Note 2: It a col of typeMapping is not found in the CSV at all, and type is a callback funtion, it will be called with (rowObj), and save to output if return value is not undefined.*~~ `Removed since v1.0.0`
#### The Task
Demo is setup with [this sheets](https://docs.google.com/spreadsheets/d/18DpYlL7ey3OTbXnTeDl82wD4ISq6iU2Gv5wCQjJsMuQ/edit#gid=1369557937).
```coffeescript
gss:
example:
options:
# from your Google API key
clientId: '785010223027.apps.googleusercontent.com'
clientSecret: 'nwQ2UedRysgbNZl6jE3I77Ji'
json: true # json or csv
prettify: true # available if options.json
files: [
options:
mapping: # available if options.json
col1: 'array'
col2: 'number'
col3: 'string'
col4: 'undefined'
col5: (val, row) ->
# 2d array
val.split('|').map (v) -> v.split ','
colNotExist: (val, row) ->
# val is undefined, and since this is the LAST mapping entry,
# the row obj passed in has already been converted accordingly
# {col1:["1","2"],col2:123,col3:"string",col5:[["1a","1b"],["2a","2b"]]}
JSON.stringify row
wrap: (out) ->
# grunt.log.error out
out
dest: 'test/Sheet1.json'
src: 'https://docs.google.com/spreadsheets/d/18DpYlL7ey3OTbXnTeDl82wD4ISq6iU2Gv5wCQjJsMuQ/edit#gid=1428256717'
,
options:
# if false, all other options will be ignored
json: false
dest: 'test/Sheet2.csv'
src: 'https://docs.google.com/spreadsheets/d/18DpYlL7ey3OTbXnTeDl82wD4ISq6iU2Gv5wCQjJsMuQ/edit#gid=1369557937'
]
```
#### Output Sheet1.json
```javascript
[
{
"col1": [
"1",
"2"
],
"col2": 123,
"col3": "string",
"col5": [
[
"1a",
"1b"
],
[
"2a",
"2b"
]
],
"colNotExist": "{\"col1\":[\"1\",\"2\"],\"col2\":123,\"col3\":\"string\",\"col5\":[[\"1a\",\"1b\"],[\"2a\",\"2b\"]]}"
},
{
"col1": [
"element1",
"element2"
],
"col2": 24.777,
"col3": "string2222",
"col5": [
[
"3",
"4"
]
],
"colNotExist": "{\"col1\":[\"element1\",\"element2\"],\"col2\":24.777,\"col3\":\"string2222\",\"col5\":[[\"3\",\"4\"]]}"
}
]
```
#### Output Sheet1.json
```csv
col1,col2,col3,col4
234,sheet,yes,no
```
## Release History
* 2014-08-05 v1.0.4 Set 0 as number default instead of null
* 2014-08-04 v1.0.3 Migrate to new `googleapis` and refactor
* 2014-07-24 v0.6.0 Add option "wrap" to process output before save, and [pull request #3](https://github.com/h0ward/grunt-gss/pull/3)
* 2014-07-19 v0.5.1 Create `col` on the go by `type` callback
* 2014-07-19 v0.5.0 Add type conversion callback. Remove 2d array support
* 2014-07-14 v0.4.6 Fetch key & gid from new gss urls, dump more useful log
* 2014-03-26 v0.4.5 Fix one more bug about deep copy
* 2014-03-26 v0.4.4 Switch to $.extend for deep copy
* 2014-03-26 v0.4.3 Fix manual array mapping
* 2014-03-07 v0.4.2 Add type boolean
* 2014-02-25 v0.4.1 Add type undefined
* 2014-02-25 v0.4.0 Add files object array to support options per file
* 2014-02-04 v0.3.0 Add typeMapping, new option to enforce field type
* 2014-01-31 v0.2.0 Implement save json, and update options
* 2014-01-29 v0.1.0 Initial release