Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

update the README

  • Loading branch information...
commit e1df25775505e58e5d54d93717668002ba8e7618 1 parent cd2fa48
Paul Campbell authored

Showing 1 changed file with 29 additions and 15 deletions. Show diff stats Hide diff stats

  1. 44  README.textile
44  README.textile
Source Rendered
@@ -4,9 +4,9 @@ Stuffing is a Rails plugin that allows you to really easily add CouchDB document
4 4
 
5 5
 I love CouchDB and I love the principles behind it. I love the flexibility of a 'schemaless' document, crash-only architecture and single file databases.
6 6
 
7  
-After prototyping a few apps using CouchDB however, I found that I was trying to bend CouchDB around corners that it just didn't fit. There are so many great things that have been developed around ActiveRecord that I take for granted every day like plugins that 'just work' : will_paginate, Paperclip, ThinkingSphinx.
  7
+After prototyping a few apps using CouchDB however, I found that I was trying to bend CouchDB around corners that it just didn't fit. There are so many great things that have been developed around ActiveRecord that I take for granted every day. Plugins that 'just work' like will_paginate, Paperclip, ThinkingSphinx.
8 8
 
9  
-Still, from playing around with CouchDB, I found I was missing some things from my experiments with it. Just adding a form field to a form and getting a per-record field. It's really nice.
  9
+Still, from playing around with CouchDB, I found myself missing some of the things from my experiments with it. Just adding a form field to a form and getting a per-record field. It's really nice.
10 10
 
11 11
 And so: Stuffing. Stuffing bridges the gap between building a completetly "ActiveRecord aware" or "ActiveRecord like" wrapper around CouchDB and simply adding the ability to add a "CouchDB" store to an existing ActiveRecord model.
12 12
 
@@ -19,7 +19,7 @@ You can install CouchDB via the CouchDB website:
19 19
 http://couchdb.apache.org/downloads.html
20 20
 
21 21
 *CouchRest*
22  
-Stuffing uses CouchDB via "jchris's CouchRest gem":http://github.com/jchris/couchrest/tree/master.
  22
+Stuffing accesses CouchDB via "jchris's CouchRest gem":http://github.com/jchris/couchrest/tree/master.
23 23
 
24 24
 <pre><code>
25 25
   sudo gem sources -a http://gems.github.com
@@ -37,16 +37,16 @@ Stuffing is a Ruby on Rails plugin. Installation is as easy as:
37 37
 h2. Example
38 38
 
39 39
 <pre><code>
40  
-class Post < ActiveRecord::Base
  40
+class Post &lt; ActiveRecord::Base
41 41
   stuffing
42 42
 end
43 43
 </code></pre>
44 44
 
45  
-This enables Stuffing by adding a 'stuffing' method to your ActiveRecord model. This method is a hash that will be persisted in CouchDB after you save or update your model.
  45
+That's all you need to get going. This enables Stuffing by adding a 'stuffing' method to your ActiveRecord model. This method is a hash that will be persisted in CouchDB after you save or update your model.
46 46
 
47  
-By default, Stuffing will connect to CouchDB on http://localhost:5984. It will use or create a CouchDB database the same name as your Rails app, as defined by your RAILS_ROOT folder and your current environment. For exmplae, if your RAILS_ROOT were /var/www/stuffing_app in production environment, by default Stuffing would use stuffing_app_development as the DB name. Documents are stored with an ID of "Class-ID", so or the example "Post" model above, document IDs in CouchDB would be "Post-1", "Post-2". "Post-3" etc.
  47
+By default, Stuffing will connect to CouchDB on http://localhost:5984. It will use or create a CouchDB database the same name as your Rails app, as defined by your RAILS_ROOT folder and your current environment. For example, if your RAILS_ROOT were /var/www/stuffing_app in production environment, by default Stuffing would use stuffing_app_development as the DB name. Documents are stored with an ID of "Class-ID", so for the example "Post" model above, document IDs in CouchDB would be "Post-1", "Post-2". "Post-3" etc.
48 48
 
49  
-To save attributes, just assign a hash to your "stuffing":
  49
+To save attributes, you can treat your 'stuffing' method like any other ActiveRecord attribute. Just assign a hash to your "stuffing":
50 50
 
51 51
 <pre><code>
52 52
   @post = Post.new
@@ -54,7 +54,7 @@ To save attributes, just assign a hash to your "stuffing":
54 54
   @post.save
55 55
 </code></pre>
56 56
 
57  
-The stuffing method can take any hash you want, which will be saved to CouchDB as JSON. Simple types (Strings, Integers etc. will be preserved.)
  57
+The stuffing method can take any hash you want, which will be saved to CouchDB as JSON. Simple types (Strings, Integers etc. will be preserved. See the CouchRest documentation for more on how this works)
58 58
 
59 59
 Your stuffing is retrieved when you load your posts via ActiveRecord:
60 60
 
@@ -72,31 +72,45 @@ A sensible set of defaults should let you get up and running with Stuffing / Cou
72 72
 You can specify a different method name for your stuffing:
73 73
 
74 74
 <pre><code>
75  
-  class Post < ActiveRecord::Base
  75
+  class Post &lt; ActiveRecord::Base
76 76
     stuffing :contents
77 77
   end
78 78
 </code></pre>
79 79
 
80 80
 This will give you @post.contents instead of @post.stuffing
81 81
 
82  
-You can also dynamically choose the host, database and Couch document ID:
  82
+You can also dynamically choose the host, database and Couch document ID. You can call any method, or method chain, prefixed by ':'
  83
+(inspired by the "interpolated path and url strings in Paperclip":http://dev.thoughtbot.com/paperclip/classes/Paperclip/Attachment.html#M000066)
83 84
 
84 85
 <pre><code>
85  
-  class Blog < ActiveRecord::Base
  86
+  class Blog &lt; ActiveRecord::Base
86 87
   end
87  
-  class Post < ActiveRecord::Base
  88
+  class Post &lt; ActiveRecord::Base
88 89
     belongs_to :blog
89  
-    stuffing :host => ':couch_host.example.com'
  90
+    stuffing :host => ':couch_host.example.com', :port => '1234', :database => 'blog-:blog.id', :id => ':class-:id-:locale'
90 91
     
91  
-    def couch_host
  92
+    def locale
  93
+      ['en', 'fr'].rand
  94
+    end
92 95
     
  96
+    def couch_host
  97
+      'subdomain'
93 98
     end
94 99
   end
95 100
 </code></pre>
96 101
 
  102
+This will connect, for example, to the 'blog-1' database on http://subdomain.example.com on port 1234, saving the stuffing document as 'Post-1-en' or 'Post-1-fr' depending on the result of the 'locale' method.
  103
+
  104
+h2. What's next
  105
+
  106
+From where I see it, this is a lot of fun and potentially kind of powerful. The plugin is well tested for basic usage. It's not, however, in any way optimised for performance.
  107
+
  108
+There's probably a lot wrong with mixing MySQL and CouchDB in this way. What this plugin is, however, is a really quick, really easy way of adding some of the most powerful features of CouchDB to your app without leaving the save, fluffy familiar world of MySQL / ActiveRecord behind.
97 109
 
  110
+h3. About me
98 111
 
99  
-Fire up CouchDB and away you go.
  112
+I'm Paul Campbell. I'm a partner in Contrast (http://www.contrast.ie) and I work on Exceptional, a Ruby on Rails exception tracker (http://getexceptional.com).
100 113
 
  114
+Follow me on Twitter http://twitter.com/paulca
101 115
 
102 116
 Copyright (c) 2009 Paul Campbell, released under the MIT license

0 notes on commit e1df257

Please sign in to comment.
Something went wrong with that request. Please try again.