Permalink
Browse files

Update README for belongs_to

  • Loading branch information...
1 parent b2348d3 commit 875f744bcc24a2f91fc9704e61f81225511b37a4 @remiprev committed Apr 11, 2012
Showing with 16 additions and 3 deletions.
  1. +16 −3 README.md
View
19 README.md
@@ -107,9 +107,9 @@ This feature is not stable and might change in the future, probably by using a m
## Relationships
-You can define `has_many` and `has_one` relationships in your models. The relationship data is handled in two different ways. When parsing a resource from JSON data, if there’s a relationship data included, it will be used to create new Ruby objects.
+You can define `has_many`, `has_one` and `belongs_to` relationships in your models. The relationship data is handled in two different ways. When parsing a resource from JSON data, if there’s a relationship data included, it will be used to create new Ruby objects.
-If no relationship data was included when parsing a resource, calling a method with the same name as the relationship will fetch the data (providing there’s an HTTP request available for it).
+If no relationship data was included when parsing a resource, calling a method with the same name as the relationship will fetch the data (providing there’s an HTTP request available for it in the API).
For example, with this setup:
@@ -118,6 +118,7 @@ class User
include Her::Model
has_many :comments
has_one :role
+ belongs_to :organization
end
class Comment
@@ -127,14 +128,19 @@ end
class Role
include Her::Model
end
+
+class Organization
+ include Her::Model
+end
```
If there’s relationship data in the resource, no extra HTTP request is made when calling the `#comments` method and an array of resources are returned:
```ruby
-@user = User.find(1) # { :data => { :id => 1, :name => "George Michael Bluth", :comments => [{ :id => 1, :text => "Foo" }, { :id => 2, :text => "Bar" }], :role => { :id => 1, :name => "Admin" } }}
+@user = User.find(1) # { :data => { :id => 1, :name => "George Michael Bluth", :comments => [{ :id => 1, :text => "Foo" }, { :id => 2, :text => "Bar" }], :role => { :id => 1, :name => "Admin" }, :organization => { :id => 2, :name => "Bluth Company" } }}
@user.comments # => [#<Comment id=1>, #<Comment id=2>] fetched directly from @user
@user.role # => #<Role id=1> fetched directly from @user
+@user.organization # => #<Organization id=2> fetched directly from @user
```
If there’s no relationship data in the resource, an extra HTTP request (to `GET /users/1/comments`) is made when calling the `#comments` method:
@@ -151,6 +157,13 @@ For `has_one` relationship, an extra HTTP request (to `GET /users/1/role`) is ma
@user.role # => #<Role id=1> fetched from /users/1/role
```
+For `belongs_to` relationship, an extra HTTP request (to `GET /organizations/2`) is made when calling the `#organization` method:
+
+```ruby
+@user = User.find(1) # { :data => { :id => 1, :name => "George Michael Bluth", :organization_id => 2 }}
+@user.organization # => #<Organization id=2> fetched from /organizations/2
+```
+
However, subsequent calls to `#comments` or `#role` will not trigger the extra HTTP request.
## Custom requests

0 comments on commit 875f744

Please sign in to comment.