= Presenter gem

This gem is mainly targeted at Rails developers who:

* need to execute a search based on request parameters
* load records from a database for cached fragments
* have a lot of view-related logic in models

It will help you to:

* process request parameters (with simple typecasting)
* cleanup your models and controller
* postpone querying database until really needed (if needed at all)
* ... more ...

== Installation

As usual:

  gem install presenter

To keep your code organized, create a directory "app/presenters" in your project and add this line to your environment.rb (or application.rb if you use Rails 3):

  config.load_paths << Rails.root.join("app", "presenters").to_s

Now you can have your presenters in the app/presenters directory and they'll be loaded automatically.

== Basic usage

Presenter:

  # app/presenters/users_presenter.rb
  class UsersPresenter < Presenter

    # following parameters will be extracted from the params hash and
    # properly typecasted. Nils, blanks and empty arrays will be discarded.
    # If a parameter's value is an array, all values in the array will
    # be typecasted
    key :name, String
    key :age, Integer

    # this creates method "users", which calls and memoizes method "find_user".
    presents :users

    private

    def find_users
      scope = User
      scope = scope.scoped(:conditions => { :name => name }) if first_name
      scope = scope.scoped(:conditions => { :age => age }) if age
      scope
    end
  end

Controller:

  # app/controllers/users_controller.rb
  class UsersController < ApplicationController

    def index
      @users_presenter = UsersPresenter.new(params)
    end
  end

View:

  # app/views/users/index.html.haml
  %ul
    - @users_presenter.users.each do |user|
      %li= user.name

== Mixins

If some of the code in your models is used only inside views (formatting and such),
you may extract this code to a module and mix it from the presenter:

  # app/presenters/user_mixin.rb
  module UserMixin
    def age_cca
      age < 20 ? "too young" : age >= 30 ? "30+" : age
    end
  end

Then tell the presented to use the module:

  # app/presenters/users_presenter.rb
  ...
  presents :users, UserMixin
  ...

Now you can use the new method in your views:

  # app/views/users/index.html.haml
  %ul
    - @users_presenter.users.each do |user|
      %li
        = user.name
        = user.age_cca

== Typecasting

These types are supported out of the box:
+Object+, +Boolean+, +Float+, +Integer+, +String+, +Time+.

All of these can be +nil+, single value or an array of values.

It is also possible to add support for your custom types by implementing class
method "typecast" for the given class. This would add support for price type:

  # lib/price.rb
  class Price

    attr :value

    def initialize(value)
      @value = value
    end

    def to_s
      if @value
        "$" + @value.to_s.reverse.scan(/\d{1,3}/).join(",").reverse
      else
        ""
      end
    end

    def self.typecast(value, options = {})
      new value.to_s.scan(/\d+/).join.to_i if value
    end
  end

== Note on Patches/Pull Requests

As usual:
 
* Fork the project.
* Make your feature addition or bug fix.
* Add tests for it. This is important so I don't break it in a
  future version unintentionally.
* Commit, do not mess with rakefile, version, or history.
  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
* Send me a pull request. Bonus points for topic branches.

== Copyright

Copyright (c) 2010 Vladimir Bobes Tuzinsky. See LICENSE for details.