Skip to content

Latest commit

 

History

History
89 lines (58 loc) · 3.18 KB

README.md

File metadata and controls

89 lines (58 loc) · 3.18 KB

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

Usage

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

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

Helpers

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" } }

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request