Mystique

Mystique is a gem that implements the presenter pattern. It allows you to augment an object, by wrapping it and giving it access to the context in which you need to render it.

How to present

Mystique ships with the .present method, which wraps the target object in a presenter and yield the presenter if a block is given, or returns it. If there default presenter is not available, the original object gets yielded/returned.

Item = Struct.new(:name, :price)
class ItemPresenter < Mystique::Presenter
end

item_presenter = Mystique.present(Item.new("Rubik's Cube", 30.5))

item_presenter.class
# => ItemPresenter

item_presenter.name
# => "Rubik's Cube"

Default presenter

The default presenter is inferred from the target object's class name. So, for the Item class, you'll get the ItemPresenter presenter.

If ItemPresenter is not defined, you'll get back your original item.

Context

The context is the object that, conveniently, provides the context in which the target object will be rendered.

Currently, the context defaults to a null context, which accepts any message sent and does nothing.

You can set the context in 3 ways:

Using the .context method when defining your presenter:

class UserPresenter < Mystique::Presenter
  context MyHelpers

  # ...
end

This will set the MyHelpers module as the context for any instance of UserPresenter

Passing it to the present method

user_presenter = Mystique.present(some_user, context: MyHelpers)

Which will set MyHelpers as the context just for user_presenter

Both

You can pass the presenter using both methods.

In that case, the one set on the class declaration will be the default one for that class, but if you pass a new context to a specific instance, it will use that one.

Formatting

Mystique provides a format method that allows you to define defaults for some response types.

In every case, format will accept a value or a block to return, which will yield the found value and the context.

Specific values

This is a great way to return a default String when you get a nil back (but it's not limited to that).

Item = Struct.new(:name, :price)
class ItemPresenter < Mystique::Presenter
  format nil, "N/A"
end

item_presenter.price
# => "N/A"

Classes

You can pass a class name to the format method, and if the returned value is an instance of that class, it will return the specified value/block

class ItemPresenter < Mystique::Presenter
  context Helpers
  format Float do |value, context|
    context.number_to_currency(value)
  end
end

item_presenter = Mystique.present(Item.new("Rubik's Cube", 5.3))

item_presenter.price
# => "$ 5.30"

Regular Expressions

You can also pass a regular expression to which the return value will be matched

module Helpers
  def self.link_to(text, url)
    "<a href='#{url}'> #{text} </a>"
  end
end

class UserPresenter < Mystique::Presenter
  context Helpers

  format /\w+@\w+\.\w+/ do |email, context|
    context.link_to(email, "mailto://#{email}")
  end
end

user_presenter = Mystique.present(User.new("Federico", "[email protected]"))

user_presenter.email
# => "<a href='mailto://[email protected]'> [email protected] </a>"

format_multiple

You can also set multiple matchers by using the .format_multiple method:

Mystique.present(Item.new("Wine", 50, 42.3)) do |presenter|
  presenter.class
  # => ItemPresenter

  presenter.price
  # => "$ 50.00"

  presenter.list_price
  # => "$ 42.30"
end

Installation

Add this line to your application's Gemfile:

gem 'mystique'

And then execute:

$ bundle

Or install it yourself as:

$ gem install mystique

Development

After checking out the repo, run bin/setup to install dependencies. Then, run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release to create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

  1. Fork it ( https://github.com/[my-github-username]/mystique/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request