README.markdown in roar-rails-1.0.1 vs README.markdown in roar-rails-1.0.2
- old
+ new
@@ -1,11 +1,20 @@
# roar-rails
_Makes using Roar's representers in your Rails app fun._
-Roar is a framework for parsing and rendering REST documents. For a better overview about representers please check the [roar repository](https://github.com/apotonick/roar#roar).
+[](https://travis-ci.org/apotonick/roar-rails)
+[](http://badge.fury.io/rb/roar-rails)
+**IMPORTANT NOTE: roar-rails 1.0.2 does not support Roar 1.1**. Support is still under development and will be released as part of roar-rails 1.1. See [#130](https://github.com/apotonick/roar-rails/issues/130).
+
+_roar-rails development will be discontinued in the future and we will encourage users to begin migrating to [Trailblazer](trailblazer.to) (and [trailblazer-rails](https://github.com/trailblazer/trailblazer-rails))._
+
+---
+
+Roar is a framework for parsing and rendering REST documents. For a better overview about representers please check the [roar repository](https://github.com/trailblazer/roar#roar).
+
Roar-rails gives you conventions and convenient access to a lot of Roar's functionality within your Rails app.
## Features
* Rendering with responders
@@ -15,11 +24,25 @@
* Autoloading
* Generators
This gem works with all Rails >= 3.x.
+## Prerequisites
+Add it to your app's `Gemfile`.
+
+```ruby
+gem "roar-rails"
+```
+
+Note: For Rails >= 4.2, you need to add the `responders` gem, too, if you use `respond_with`. This has to be before the `roar-rails` entry in the Gemfile.
+
+```ruby
+gem "responders"
+gem "roar-rails"
+```
+
## Generators
The generator will create the representer modules in `app/representers` for you.
Here's an example.
@@ -168,10 +191,11 @@
If you prefer roar's decorator approach over extend, just go for it. roar-rails will figure out automatically which represent strategy to use. Be sure to use roar >= 0.11.17.
```ruby
class SingerRepresenter < Roar::Decorator
include Roar::JSON
+ include Roar::Hypermedia
property :name
link :self do
singer_url(represented)
@@ -227,11 +251,11 @@
```ruby
config.representer.default_url_options = {:host => "127.0.0.1:3000"}
```
-Attention: If you are using representers from a gem your Rails URL helpers might not work in these modules. This is due to a [loading order problem](https://groups.google.com/forum/?fromgroups#!topic/rubyonrails-core/5tG5unZ8jDQ) in Rails. As a workaround, don't require the representers in the gem but load them as lately as possible, usually it works when you require in the controller. We are working on fixing that problem.
+Attention: If you are using representers from a gem your Rails URL helpers might not work in these modules. This is due to a [loading order problem](https://groups.google.com/forum/?fromgroups#!topic/rubyonrails-core/5tG5unZ8jDQ) in Rails. As a workaround, don't require the representers in the gem but load them as late as possible, usually it works when you require in the controller. We are working on fixing that problem.
## Representing Formats Exclusively
By default, roar-rails will extend/decorate any model passed to `respond_with` for any request format. When adding roar-rails to a legacy project, you might want to restrict roar-rails' representing and fall back to the old behavior for certain formats. This can be configured both globally and on a per action basis.
@@ -267,9 +291,19 @@
## Testing
## Autoloading
Put your representers in `app/representers` and they will be autoloaded by Rails. Also, frequently used modules as media representers and features don't need to be required manually.
+
+## JSON-API
+
+In a JSON-API environment, only one representer is written for both singular and collection resources. However, you have to configure `represents` accordingly so it knows what representer to use for collections.
+
+```ruby
+class SongsController < ApplicationController
+ represents :json_api, entity: SongRepresenter, collection: SongRepresenter.for_collection
+```
+
## Rails 4.1+ and HAL/JSON-API
**Note**: this is a temporary work-around, we're trying to fix that in Rails/roar-rails itself [May 2014].