Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 120 lines (86 sloc) 3.896 kb
49355262 »
2012-05-07 Initial commit
1 # SheetMapper
2
defd263e »
2012-05-20 Adds rationale to readme
3 SheetMapper is about taking a google spreadsheet and converting a set of data rows into simple ruby objects.
81c4ebdd »
2012-05-07 Update readme
4
dc455487 »
2012-05-08 Spruce up readme
5 ## Installation
6
7 Setup in Gemfile:
8
9 ```ruby
10 # Gemfile
11
12 gem 'sheet_mapper'
13 ```
14
15 and then `require 'sheet_mapper'` and you are done!
16
defd263e »
2012-05-20 Adds rationale to readme
17 ## Rationale
18
19 You may ask why you would need to have an object mapper from a Google Spreadsheet. Consider though that spreadsheets are collaborative, have revision tracking, securely authenticated, are accessible anywhere and are familiar to non-technical people.
20
21 If you ever needed a dead simple admin interface, configuration document, or basic content management system, a spreadsheet is a pretty great solution that requires very little engineering overhead. Next time you are in a position where non-technical people
22 need to manage data, ask yourself if a spreadsheet might be a good first solution.
23
81c4ebdd »
2012-05-07 Update readme
24 ## Usage
25
b8f0bca9 »
2012-05-20 Minor change to readme
26 First, you describe how to map a spreadsheet into data rows with a sheet object mapper:
49355262 »
2012-05-07 Initial commit
27
28 ```ruby
50f95cbe »
2012-05-15 Simplify readme example
29 class SomeMapper < SheetMapper::Base
81c4ebdd »
2012-05-07 Update readme
30 # Defines each column for a row and maps each column to an attribute
76b9cfc7 »
2012-05-20 Update readme with a few notes
31 # Should be listed in the order the data appears in the spreadsheet
50f95cbe »
2012-05-15 Simplify readme example
32 columns :foo, :bar, :baz
49355262 »
2012-05-07 Initial commit
33
81c4ebdd »
2012-05-07 Update readme
34 # Defines the condition for a row to be considered valid
76b9cfc7 »
2012-05-20 Update readme with a few notes
35 # Also have access to `pos` which is the row number in the worksheet
49355262 »
2012-05-07 Initial commit
36 def valid_row?
76b9cfc7 »
2012-05-20 Update readme with a few notes
37 self[:foo].present? && self.pos > 2
49355262 »
2012-05-07 Initial commit
38 end
39
76b9cfc7 »
2012-05-20 Update readme with a few notes
40 # Convert bar column to a boolean from raw string
41 # Any method named after a column will override the default value
42 def bar
50f95cbe »
2012-05-15 Simplify readme example
43 !!self[:bar].match(/true/i)
49355262 »
2012-05-07 Initial commit
44 end
45 end
46 ```
47
264240b3 »
2012-05-16 Add LICENSE and clarify readme
48 The mapper describes the column mappings and transformations to turn a spreadsheet row into a ruby object. Then you can apply
49 a mapper to any worksheet (collection):
49355262 »
2012-05-07 Initial commit
50
51 ```ruby
264240b3 »
2012-05-16 Add LICENSE and clarify readme
52 # Login and access a particular spreadsheet by key
237d43fd »
2012-05-16 More readme tweaks
53 sheet = SheetMapper::Spreadsheet.new(:mapper=>SomeMapper, :key=>'k', :login => 'u', :password => 'p')
264240b3 »
2012-05-16 Add LICENSE and clarify readme
54 # Find a particular worksheet (collection) by title
49355262 »
2012-05-07 Initial commit
55 collection = sheet.find_collection_by_title('title')
264240b3 »
2012-05-16 Add LICENSE and clarify readme
56 # Iterate over the records within the worksheet
10e58dca »
2012-05-15 Fix readme example
57 records = collection.each do |record|
58 p record.attributes
59 # => { :foo => "...", :bar => false, ... }
49355262 »
2012-05-07 Initial commit
60 end
81c4ebdd »
2012-05-07 Update readme
61 ```
62
a9b44e44 »
2012-05-20 Adds persistence to readme
63 You can then work with objects within the collection and access their attributes. You can also modify objects and
64 persist the changes back to the collection (worksheet):
65
66 ```ruby
67 # Fetch the second data row from the spreadsheet
68 record = collection.records[1]
69 record[:foo] = "other"
70 # Persist change of value to worksheet
71 collection.save
72 # or more explicitly collection.save(record)
73 ```
74
75 If you want to reset changes made to your records, just use the reload method:
76
77 ```ruby
78 # Fetch the second data row from the spreadsheet
79 record = collection.records[1]
80 record[:foo] = "other"
81 # Reset unsaved changes
82 collection.reload
83 ```
84
85 You may also come across situations where you need access to 'meta' information associated with the collection.
86 Use the 'cell' method to access arbitrary data points:
264240b3 »
2012-05-16 Add LICENSE and clarify readme
87
88 ```ruby
89 # Accesses row 1, column 2 within the worksheet
90 collection.cell(1, 2) => "foo"
91 ```
dc455487 »
2012-05-08 Spruce up readme
92
93 ## Contributors
94
d0de850d »
2012-06-12 Adds Derek to readme as first contributor
95 SheetMapper was created by [Nathan Esquenazi](http://github.com/nesquena) at Miso in 2012. The following users
96 contributed to the project:
97
82029ee6 »
2012-06-12 Fix link for contributors
98 * [Derek Lindahl](https://github.com/dlindahl) - Added simple delegation to collections
264240b3 »
2012-05-16 Add LICENSE and clarify readme
99
100 ## Tasks
101
4c9af66b »
2012-05-24 Adds task notes
102 SheetMapper is a new gem and I would love any feedback and/or pull requests. In particular:
103
104 * Inserting a data row into a collection
105 * Removing a data row from a collection
106 * Callbacks
107 * Validations
108 * Column Type Casting
109
110 Please fork if you are inspired to add any of these or any other improvements.
264240b3 »
2012-05-16 Add LICENSE and clarify readme
111
c730278b »
2012-05-16 Adds travis-ci to readme
112 ## Continuous Integration ##
113
114 [![Continuous Integration status](https://secure.travis-ci.org/nesquena/sheet_mapper.png)](http://travis-ci.org/nesquena/sheet_mapper)
115
116 CI is hosted by [travis-ci.org](http://travis-ci.org).
117
264240b3 »
2012-05-16 Add LICENSE and clarify readme
118 ## License
119
120 Check `LICENSE` but of course feel free to use this in any projects.
Something went wrong with that request. Please try again.