README.md

Grape::Rabl

Use Rabl templates in Grape!

Installation

Add the grape and grape-rabl gems to Gemfile.

gem 'grape'
gem 'grape-rabl'

And then execute:

$ bundle

Upgrading

See UPGRADING.

Usage

Setup view root directory

# config.ru
use Rack::Config do |env|
  env['api.tilt.root'] = '/path/to/view/root/directory'
end

Tell your API to use Grape::Formatter::Rabl

class API < Grape::API
  format :json
  formatter :json, Grape::Formatter::Rabl
end

Use rabl templates conditionally

Add the template name to the API options.

get "/user/:id", :rabl => "user.rabl" do
  @user = User.find(params[:id])
end

You can use instance variables in the Rabl template.

object @user => :user
attributes :name, :email

child @project => :project do
  attributes :name
end

Use rabl layout

Gape-rabl first looks for a layout file in #{env['api.tilt.root']}/layouts/application.rabl.

You can override the default layout conventions:

# config.ru
use Rack::Config do |env|
  env['api.tilt.root'] = '/path/to/view/root/directory'
  env['api.tilt.layout'] = 'layouts/another'
end

Enable template caching

Grape-rabl allows for template caching after templates are loaded initially.

You can enable template caching:

# config.ru
Grape::Rabl.configure do |config|
  config.cache_template_loading = true # default: false
end

You can omit .rabl

The following are identical.

get "/home", :rabl => "view"
get "/home", :rabl => "view.rabl"

Example

# config.ru
use Rack::Config do |env|
  env['api.tilt.root'] = '/path/to/view/root/directory'
end

class UserAPI < Grape::API
  format :json
  formatter :json, Grape::Formatter::Rabl

  get '/user/:id' do
    @user = User.find(params[:id])

    # use rabl with 'user.rabl' or 'admin.rabl' template
    if @user.admin?
      # pass locals with the #render method
      render rabl: 'admin', locals: { details: 'this user is an admin' }
    else
      render rabl: 'user'
    end
  end

  get '/admin/:id', :rabl => 'admin' do
    @user = User.find(params[:id])

    # use rabl with 'super_admin.rabl'
    render rabl: 'super_admin' if @user.super_admin?
    # when render method has not been used use template from endpoint definition
  end

  # use rabl with 'user_history.rabl' template
  get '/user/:id/history', :rabl => 'user_history' do
    @history = User.find(params[:id]).history
  end

  # do not use rabl, fallback to the default Grape response formatter
  get '/users' do
    User.all
  end
end

# user.rabl
object @user => :user

attributes :name

Usage with rails

Create grape application

# app/api/user.rb
class MyAPI < Grape::API
  format :json
  formatter :json, Grape::Formatter::Rabl
  get '/user/:id', :rabl => "user" do
    @user = User.find(params[:id])
  end
end

# app/views/api/user.rabl
object @user => :user

Edit your config/application.rb and add view path

# application.rb
class Application < Rails::Application
  config.middleware.use(Rack::Config) do |env|
    env['api.tilt.root'] = Rails.root.join "app", "views", "api"
  end
end

Mount application to rails router

# routes.rb
GrapeExampleRails::Application.routes.draw do
  mount MyAPI , :at => "/api"
end

Specs

See "Writing Tests" in grape README.

Enjoy :)

Contributing

See CONTRIBUTING.