Git Product home page Git Product logo

jbuilder's Introduction

JBuilder JSON Templating

JBuilder is a simple templating engine for generating JSON output. With Builder-like DSL it allows you to have your controllers and models clean of view logic. Primarily for Rails, but no reason not be used elsewhere. It was inspired by Builder gem and it uses JSON gem in the background.

Motivation

A while ago I was implementing a REST API in Rails3 for my latest project and I choose JSON for primary content type. After an easy start with Rails and JSON based API, I found myself struggling to implement according to the MVC pattern. It gets even more annoying, when your API is growing beyond simplest example and when you want to have more control over the output format and logic.

Rails usually tackles this challenge in one of three ways:

  • generating a simple JSON object in controller

  • or keeping the controller clean, but putting the generating code into model’s to_json method

  • or having the view done in default ERB template

First two approaches are strongly oppossing MVC pattern, having the view logic in either controller or model. Third is just too cumbersome, since ERB was meant for generating XML/HTML - and even there it doesn’t exactly shine. (If you disagree, check HAML ;)

What I was really missing was a simple templating for generating JSON output, something like Builder is for XML. If you ask me, this should come with Rails out of the box along with ERB and Builder.

Here is the solution - a Builder-like JSON templating.

Examples and Usage

Let’s say you want to produce output like this:

{
  "user":
  {
    "id":13,
    "nickname":"antiveb",
    "email":"[email protected]",
    "twitter_data":
    {
      "key":"7325872",
      "token":"0",
      "secret":"0",
      "friends": [ 10, 20, 30 ],
      "followers": [ 20, 30 ]
    }
  }
}

Your code would then look like this:

json.user do
  json.value :id, 13
  json.nickname   "antiveb"
  json.email      "[email protected]"
  json.twitter_data do
    json.key     "7325872"
    json.token   "0"
    json.secret  "0"
    json.friends [10, 20, 30]
    json.followers :array do
      json.element 20
      json.element 30
    end
  end
end

Some rules, how to write directives:

  • every directive is prefixed with json.

  • there are three directive types (methods), that can be directly invoked: value, array, object

  • all three directive types take 2 parameters: name and value

  • if the directive is not one of those mentioned, there is a shorthand directive that tries to guess the directive type from arguments

  • shorthand directive takes the directive name as the first argument and value as the second argument

Setup

Just install the gem and require it in your Gemfile: gem “jbuilder”, :git => “git://github.com/antiveb/JBuilder.git”

Improving the docs

If you find something confusing or encounter a problem with this instructions please fork this project, make the changes, and send me a pull request.

Contact

Author:    Uros Jurglic
Company:   Antiveb ltd.
Email:     [email protected]
Home Page: www.antiveb.com
License:   MIT Licence (www.opensource.org/licenses/mit-license.html)

jbuilder's People

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.