Bldr

Bldr is a minimalist templating DSL that provides a simple syntax for generating json documents from ruby objects. Bldr supports Sinatra and Rails 3.2.

Bldr enables to quickly generate json documents from ruby with a simple and intuitive DSL.

# app/views/posts/index.json.bldr

collection @posts do |post|
  attributes :title, :body, :created_at, :slug
  
  object :author => post.author do |author|
    attribute(:name) { author.display_name }
  end

  collection :comments => post.comments do |comment|
    attribute :spamminess
    attribute :created_at
    attribute(:body) do
      xss_filter(comment.body)
    end
  end
end

This would output the following json document:

[
  {
    "title": "Some title",
    "body": "blah blah",
    "slug": "some-title",
    "created_at": "2013-04-11T15:46:17-07:00",
    "author": {
      "name": "Joe Author"
    },
    "comments": [
      {
        "spamminess": 1.0,
        "created_at": "2013-04-11T15:46:17-07:00",
        "body": "a comment"
      }
    ]
  }
]

Bldr is a very concise DSL, containing only four core methods:

• object
• collection
• attribute
• attributes

These four methods provide a great deal of power and flexibility in describing json responses.

If you're building an API, Model#to_json just doesn't cut it. Besides the JSON representation of your models arguably being a presentation concern, trying to cram all of this logic into an #as_json method quickly turns into pure chaos.

There are other json templating libraries available such as rabl or json_builder. Bldr is in the same vein as these libraries, but with a simpler synxtax.

See Examples on the wiki for documentation and usage examples.

In your gemfile:

gem 'bldr'

No additional configuration is required for rails applications.

For sinatra apps, dependening on whether you're using a modular or classic application style, do one of the following:

# Method 1: Classic style

require 'sinatra/bldr'

get '/hello' do
  bldr :hello
end


# Method 2: Modular style

require 'sinatra/bldr'

class MyApp < Sinatra::Base
  register Sinatra::Bldr
end

The use of current_object is now deprecated. Instead of referencing current_object in bldr templates use block variables in object and collection methods:

# OLD (deprecated)
collection :people => people do
  attribute(:name) { current_object.name }
end

# NEW
collection :people => people do |person|
  attribute(:name) { person.name }
end

Make use of block variables the same way for the object method:

# OLD (deprecated)
object :person => person do
  attributes :name, :age

  person = current_object
  object :address => person.address do
    # current_object here would be assigned to person.address
    attribute(:zip) { current_object.zip_code }
    attribute(:address_title) { person.display_name }
  end
end

# NEW
object :person => person do |person|
  attributes :name, :age

  object :adress => person.address do |address|
    attribute(:zip) { address.zip_code }
    attribute(:address_title) { person.display_name }
  end
end

One of the forms of the attribute method has changed in the 0.7.0 release. Previously, using the dynamic block form of attribute, if you did not pass in a block variable, the block would be eval'd in context of the current_object. This behavior fails the "principle of least surprise" test.

0.7.0 changes this behavior by simply executing the block in context of Bldr::Node, which provides access to instance variables and locals available in that context.

# OLD
object :person => person do
  attribute(:name) { display_name } # equivalent to doing attribute(:name) { |person| person.display_name }
end

# NEW
object :person => @person do
  attribute(:name) { @person.display_name }
end

See 941608e and d0bfbd8 for more info.

Add this line to your .vimrc:

au BufRead,BufNewFile *.bldr set filetype=ruby

Add this to your ~/.emacs.d/init.el:

(add-to-list 'auto-mode-alist '("\\.bldr$" . ruby-mode))

• XML support

• RABL - Inspiration
• Tilt - Mega awesome templating goodness

• Ian Hunter (@ihunter)
• Justin Smestad (@jsmestad)
• Adam LaFave (@lafave)

Copyright (c) 2011-2013 Alex Sharp. See the MIT-LICENSE file for full copyright information.