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
- Fork it ( https://github.com/[my-github-username]/mystique/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request