From 6702574b32b134f63d9a689f7d065e3200c8425b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20Tapaj=C3=B3s?= Date: Wed, 13 Jan 2010 21:07:59 -0200 Subject: [PATCH] moving all examples to wiki --- README.md | 164 +----------------------------------------------------- 1 file changed, 2 insertions(+), 162 deletions(-) diff --git a/README.md b/README.md index fa8952b..a1a9e29 100644 --- a/README.md +++ b/README.md @@ -14,11 +14,6 @@ Note: CouchRest only support CouchDB 0.9.0 or newer. $ sudo gem install couchrest -Alternatively, you can install from Github: - - $ gem sources -a http://gems.github.com (you only have to do this once) - $ sudo gem install couchrest-couchrest - ### Relax, it's RESTful CouchRest rests on top of a HTTP abstraction layer using by default Heroku’s excellent REST Client Ruby HTTP wrapper. @@ -30,164 +25,9 @@ The most complete documentation is the spec/ directory. To validate your CouchRest install, from the project root directory run `rake`, or `autotest` (requires RSpec and optionally ZenTest for autotest support). -## Examples (CouchRest Core) +### Docs -Quick Start: - - # with !, it creates the database if it doesn't already exist - @db = CouchRest.database!("http://127.0.0.1:5984/couchrest-test") - response = @db.save_doc({:key => 'value', 'another key' => 'another value'}) - doc = @db.get(response['id']) - puts doc.inspect - -Bulk Save: - - @db.bulk_save([ - {"wild" => "and random"}, - {"mild" => "yet local"}, - {"another" => ["set","of","keys"]} - ]) - # returns ids and revs of the current docs - puts @db.documents.inspect - -Creating and Querying Views: - - @db.save_doc({ - "_id" => "_design/first", - :views => { - :test => { - :map => "function(doc){for(var w in doc){ if(!w.match(/^_/))emit(w,doc[w])}}" - } - } - }) - puts @db.view('first/test')['rows'].inspect - - -## CouchRest::ExtendedDocument - -CouchRest::ExtendedDocument is a DSL/ORM for CouchDB. Basically, ExtendedDocument seats on top of CouchRest Core to add the concept of Model. -ExtendedDocument offers a lot of the usual ORM tools such as optional yet defined schema, validation, callbacks, pagination, casting and much more. - -### Model example - -Check spec/couchrest/more and spec/fixtures/more for more examples - - class Article < CouchRest::ExtendedDocument - use_database DB - unique_id :slug - - view_by :date, :descending => true - view_by :user_id, :date - - view_by :tags, - :map => - "function(doc) { - if (doc['couchrest-type'] == 'Article' && doc.tags) { - doc.tags.forEach(function(tag){ - emit(tag, 1); - }); - } - }", - :reduce => - "function(keys, values, rereduce) { - return sum(values); - }" - - property :date - property :slug, :read_only => true - property :title - property :tags, :cast_as => ['String'] - - timestamps! - - save_callback :before, :generate_slug_from_title - - def generate_slug_from_title - self['slug'] = title.downcase.gsub(/[^a-z0-9]/,'-').squeeze('-').gsub(/^\-|\-$/,'') if new? - end - end - -### Callbacks - -`CouchRest::ExtendedDocuments` instances have 4 callbacks already defined for you: - `:validate`, `:create`, `:save`, `:update` and `:destroy` - -`CouchRest::CastedModel` instances have 1 callback already defined for you: - `:validate` - -Define your callback as follows: - - set_callback :save, :before, :generate_slug_from_name - -CouchRest uses a mixin you can find in lib/mixins/callbacks which is extracted from Rails 3, here are some simple usage examples: - - set_callback :save, :before, :before_method - set_callback :save, :after, :after_method, :if => :condition - set_callback :save, :around {|r| stuff; yield; stuff } - - Or the aliased short version: - - before_save :before_method, :another_method - after_save :after_method, :another_method, :if => :condition - around_save {|r| stuff; yield; stuff } - -To halt the callback, simply return a :halt symbol in your callback method. - -Check the mixin or the ExtendedDocument class to see how to implement your own callbacks. - -### Properties - - property :last_name, :alias => :family_name - property :read_only_value, :read_only => true - property :name, :length => 4...20 - property :price, :type => Integer - -Attribute protection from mass assignment to CouchRest properties. There are two modes of protection: - -1) Declare accessible properties, assume all the rest are protected - property :name, :accessible => true - property :admin # this will be automatically protected - -2) Declare protected properties, assume all the rest are accessible - property :name # this will not be protected - property :admin, :protected => true - -Note: you cannot set both flags in a single class - -### Casting - -Often, you will want to store multiple objects within a document, to be able to retrieve your objects when you load the document, -you can define some casting rules. - - property :casted_attribute, :cast_as => 'WithCastedModelMixin' - property :keywords, :cast_as => ["String"] - property :occurs_at, :cast_as => 'Time', :init_method => 'parse - property :end_date, :cast_as => 'Date', :init_method => 'parse - -If you want to cast an array of instances from a specific Class, use the trick shown above ["ClassName"] - -### Pagination - -Pagination is available in any ExtendedDocument classes. Here are some usage examples: - -basic usage: - - Article.all.paginate(:page => 1, :per_page => 5) - -note: the above query will look like: `GET /db/_design/Article/_view/all?include_docs=true&skip=0&limit=5&reduce=false` and only fetch 5 documents. - -Slightly more advance usage: - - Article.by_name(:startkey => 'a', :endkey => {}).paginate(:page => 1, :per_page => 5) - -note: the above query will look like: `GET /db/_design/Article/_view/by_name?startkey=%22a%22&limit=5&skip=0&endkey=%7B%7D&include_docs=true` -Basically, you can paginate through the articles starting by the letter a, 5 articles at a time. - - -Low level usage: - - Article.paginate(:design_doc => 'Article', :view_name => 'by_date', - :per_page => 3, :page => 2, :descending => true, :key => Date.today, :include_docs => true) +Check the wiki for documentation and examples [http://wiki.github.com/couchrest/couchrest](http://wiki.github.com/couchrest/couchrest) ## Ruby on Rails