HalPresenters

Extracted from dtime.com codebase, still needs a lot of cleaning up.

Installation

Add this line to your application's Gemfile:

gem 'hal_presenters'

And then execute:

$ bundle

Or install it yourself as:

$ gem install hal_presenters

Presenter Objects:

Presenters respond to #present which takes a presentation_type argument :full vs :embedded
Presenters mix in HalPresenters::Helpers::Hypermedia, which in turn mixes in a bunch of helpers. These define some DSL methods that can be used, such as #self.exposes, #self.expose_embedded, and #self.rel.
Most of the helpers "expose" an attribute to the world in some way. To see an attribute defined on a model, it has to be "exposed".
Most of the helpers run as filters called by the #present method, allowing them to be disabled if necessary.

Presentation Helper

ThingyPresenter.new(model or hashie::mash)
Presenter#present(:full) => Presenter#full (returns hash-like obj) (called by PresentationHelpers::Present#present)
run through default_filters, each takes in the object and returns a modified version (called by PresentationHelpers::Present)
run through presentation specific filters, each takes in the object and returns a modified version (called by PresentationHelpers::Present)
run default_after_filters, each takes in the object and returns a modified version (called by PresentationHelpers::Present)
Hash-like object ready for JSON rendering (returned by HalPresenters::Helpers::Present#present)

Present

#self.presentation defines a named presentation and set of filters to run when that presentation is called. A lot of the other helper classes are filters that can be optionally included in a presentation.

presentation :full, :linkify, :embedify Will define a presentation of :full with #linkify and #embedify filters called on the object before returning it.

Presentation filters must take in a Hashie::Mash like object, and return a modified version of the object back out.

Emeddable

#self.expose_embedded which will expose an attribute as an embedded object for hal:

expose_embedded :user, UserPresenter will make it so when the item is presented, it has the option of embedding user.
#embedify will actually include the user in the output object of #present

Rels

#self.rel lets you define a rel to include when calling #linkify. This method takes an opts array that can define :only => [] or :except => [] to exclude it or include it on certain presentations (:only => :full, :except => :special_case)

rel "dtime:item" do "/items/#{model.item_id}" end Defines a rel that takes the model's item_id and build a url for it
#linkify - takes the rels defined and puts them in items, taking into account the :onlys and the :excepts.

{ _links: { "dtime:foo": "/items/bar" } }