moving all examples to wiki
This commit is contained in:
Marcos Tapajós
parent
4a8015b119
commit
6702574b32
1 changed files with 2 additions and 162 deletions
164
README.md
164
README.md
|
|
@ -14,11 +14,6 @@ Note: CouchRest only support CouchDB 0.9.0 or newer.
|
||||||
|
|
||||||
$ sudo gem install couchrest
|
$ 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
|
### Relax, it's RESTful
|
||||||
|
|
||||||
CouchRest rests on top of a HTTP abstraction layer using by default Heroku’s excellent REST Client Ruby HTTP wrapper.
|
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`
|
CouchRest install, from the project root directory run `rake`, or `autotest`
|
||||||
(requires RSpec and optionally ZenTest for autotest support).
|
(requires RSpec and optionally ZenTest for autotest support).
|
||||||
|
|
||||||
## Examples (CouchRest Core)
|
### Docs
|
||||||
|
|
||||||
Quick Start:
|
Check the wiki for documentation and examples [http://wiki.github.com/couchrest/couchrest](http://wiki.github.com/couchrest/couchrest)
|
||||||
|
|
||||||
# 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)
|
|
||||||
|
|
||||||
## Ruby on Rails
|
## Ruby on Rails
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue