couchrest_model/README.md

100 lines
3.6 KiB
Markdown
Raw Normal View History

2009-01-11 11:27:22 +01:00
# CouchRest: CouchDB, close to the metal
2008-09-07 21:54:22 +02:00
2008-10-02 19:57:13 +02:00
CouchRest is based on [CouchDB's couch.js test
library](http://svn.apache.org/repos/asf/incubator/couchdb/trunk/share/www/script/couch.js),
which I find to be concise, clear, and well designed. CouchRest lightly wraps
CouchDB's HTTP API, managing JSON serialization, and remembering the URI-paths
to CouchDB's API endpoints so you don't have to.
2008-09-07 21:54:22 +02:00
2009-01-16 00:05:55 +01:00
CouchRest is designed to make a simple base for application and framework-specific object oriented APIs. CouchRest is Object-Mapper agnostic, the parsed JSON it returns from CouchDB shows up as subclasses of Ruby's Hash. Naked JSON, just as it was mean to be.
2008-09-07 21:54:22 +02:00
2009-01-11 11:27:22 +01:00
## Easy Install
2008-09-07 21:54:22 +02:00
2009-01-11 11:27:22 +01:00
Easy Install is moving to RubyForge, heads up for the gem.
2008-09-07 21:54:22 +02:00
2009-01-11 11:27:22 +01:00
### Relax, it's RESTful
2008-09-07 21:54:22 +02:00
2008-10-02 19:57:13 +02:00
The core of Couchrest is Herokus excellent REST Client Ruby HTTP wrapper.
REST Client takes all the nastyness of Net::HTTP and gives is a pretty face,
while still giving you more control than Open-URI. I recommend it anytime
youre interfacing with a well-defined web service.
2008-09-07 21:54:22 +02:00
2009-01-11 11:27:22 +01:00
### Running the Specs
2008-09-07 21:54:22 +02:00
2008-10-02 19:57:13 +02:00
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).
2008-09-07 21:54:22 +02:00
2009-01-11 11:27:22 +01:00
## Examples
2008-09-07 21:54:22 +02:00
Quick Start:
# with !, it creates the database if it doesn't already exist
2008-12-14 12:05:02 +01:00
@db = CouchRest.database!("http://127.0.0.1:5984/couchrest-test")
2009-01-29 08:04:22 +01:00
response = @db.save_doc({:key => 'value', 'another key' => 'another value'})
2008-09-07 21:54:22 +02:00
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:
2009-01-29 08:04:22 +01:00
@db.save_doc({
2008-09-07 21:54:22 +02:00
"_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
2009-01-11 11:27:22 +01:00
## CouchRest::Model
2008-09-07 21:54:22 +02:00
2008-10-02 19:52:33 +02:00
CouchRest::Model is a module designed along the lines of DataMapper::Resource.
By subclassing, suddenly you get all sorts of powerful sugar, so that working
with CouchDB in your Rails or Merb app is no harder than working with the
standard SQL alternatives. See the CouchRest::Model documentation for an
example article class that illustrates usage.
2009-01-11 11:27:22 +01:00
CouchRest::Model will be removed from this package.
## CouchRest::ExtendedDocument
### Callbacks
`CouchRest::ExtendedDocuments` instances have 2 callbacks already defined for you:
`create_callback`, `save_callback`, `update_callback` and `destroy_callback`
In your document inherits from `CouchRest::ExtendedDocument`, define your callback as follows:
save_callback :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:
save_callback :before, :before_method
save_callback :after, :after_method, :if => :condition
save_callback :around {|r| stuff; yield; stuff }
Check the mixin or the ExtendedDocument class to see how to implement your own callbacks.
### 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"]
If you want to cast an array of instances from a specific Class, use the trick shown above ["ClassName"]