view 1.0.0.alpha.1

data/README.rdoc

@@ -0,0 +1,158 @@
+= View
+
+Automatic viewer. Very configurable. Very flexible. Very alpha (for now).
+
+It is made for displaying stuff in views. This can be very handy for DSLs that create views.
+Some of those DSLs are coming soon to a rubygem near you!
+
+But first, the view!
+
+== Usage
+
+Use it from your views:
+
+  = view @post
+
+View will try to figure out what the most logical way is to present the object you passed in.
+If the @post object has a title for instance, it will use that.
+
+See the auto formatter for more information.
+
+You can use view anywhere you like:
+
+  puts View.to_s(@post)
+
+But beware that for many formatters, a reference to the template is required.
+It is a helper for the view part of your application after all.
+
+== Options
+
+View will automatically try to choose the proper formatter. You can specify a formatter yourself:
+
+  = view @post.created_at, :as => :date
+
+You can add a block to specify your own behavior. The parsed value is passed in as a block-variable.
+
+  = view @post.author do |author|
+    = link_to author, @post.author
+
+Most formatters pass their options down to the method they use, such as the image formatter:
+
+  = view @user.avatar, :as => :image, :size => "40x40", :class => "avatar"
+
+== Examples
+
+There are many formatters included (18 and counting), but here are some interesting use cases of some of them.
+
+  # Options are passed to the helper methods:
+  = view @post, :as => :link, :method => :delete, :confirm => "are you sure?"
+
+  # Renders a link to the edit_page of the post:
+  = view @post, :as => :link, :path => [ :edit ]
+
+  # Renders a sentence of links:
+  = view Post.all, :each => { :as => :link }
+
+  # When using paperclip, renders the image:
+  = view @project.logo, :as => :image
+
+  # Renders "yes" or "no" (with I18n support!)
+  = view @user.admin?
+
+See the formatters in lib/views/formatters to see their full documentation.
+
+== Adding formatters
+
+You can add a formatter by inheriting from View::Formatter.
+The only method you need to implement is the to_s method.
+
+In the class you have access to the following methods:
+
+* value: the object passed in
+* options: a filtered hash of options
+* all_options: the unfiltered hash
+* template: call methods like link_to on this
+
+If you wanted a uppercase formatter for example, you could do this:
+
+  class Uppercase < View::Formatter
+
+    def to_s
+      value.to_s.upcase
+    end
+
+  end
+
+The name of the formatter is automatically infered from the name of the class.
+
+You can use the .as method to specify a different name.
+
+  class Foo < View::Formatter
+    as :bar
+    # etc ...
+  end
+
+You can control which options are allowed, by adding reserved options:
+
+  class Foo < View::Formatter
+    self.reserved_options = [ :foo, :bar ]
+  end
+
+Now, the options method will return the options passed by the user, minus foo and bar.
+To use them, in your code, use the all_options method.
+This is done to easily pass the options to another method, without cluttering:
+
+  class Paragraph < View::Formatter
+    def to_s
+      template.content_tag(:p, value.to_s, options)
+    end
+  end
+
+To more tightly control which options are allowed, specify the allowed_options.
+
+  class Size < View::Formatter
+    self.allowed_options = [ :separator, :delimiter, :precision ]
+    def to_s
+      template.number_to_human_size(value, options)
+    end
+  end
+
+You can use the existing formatters as examples.
+
+== Configuration:
+
+See lib/view.rb for information on configuration.
+
+== Installation
+
+=== Rails 3
+
+In Rails 3, just add it to your Gemfile:
+
+  gem 'view'
+
+Run <tt>bundle install</tt> and you're ready to go!
+
+=== Rails 2
+
+In Rails 2, add it to app/environment.rb:
+
+  config.gem 'view'
+
+And run <tt>rake gems:install</tt> to get it.
+
+Afterwards, include the helper mehtod manually, by editing app/helpers/application_helper.rb:
+
+  module ApplicationHelper
+    include View::Helper
+  end
+
+Caution: some helpers may use new helper methods from Rails 3 and might not work in Rails 2.
+
+== Contributing
+
+Yes please! You know the drill: fork, commit, pull request, profit!
+
+== License
+
+Copyright 2010 Iain Hecker (iain@iain.nl), released under the MIT License.

data/init.rb

@@ -0,0 +1 @@
+require 'view'

data/lib/view/formatter.rb

@@ -0,0 +1,134 @@
+module View
+
+  class Formatter
+
+    attr_reader :value, :template, :block
+
+    class_inheritable_accessor :default_options
+    self.default_options = {}
+
+    class_inheritable_array :reserved_options
+    self.reserved_options = [ :as, :block_arguments ]
+
+    class_inheritable_array :allowed_options
+    self.allowed_options = []
+
+    def initialize(value, options = {}, template = nil, &block)
+      @value    = value
+      @options  = options
+      @template = template
+      @block    = block
+    end
+
+    def self.inherited(formatter)
+      super
+      formatters.unshift(formatter)
+    end
+
+    def self.formatters
+      View.formatters ||= []
+    end
+
+    def self.as(type)
+      @type = type
+    end
+
+    def self.type
+      @type || name.split('::').last.underscore
+    end
+
+    def self.to_s(*args, &block)
+      new(*args, &block).format
+    end
+
+    def format
+      if block
+        captured_value
+      else
+        formatted_value
+      end
+    end
+
+    def to_s
+      msg <<-MSG.squeeze(' ')
+        The only thing a formatter needs to do is implement the #to_s method.
+        If you see this error, you forgot to do that for the #{self.class.type} formatter.
+      MSG
+      raise NotImplementedError.new(msg)
+    end
+
+    def options
+      default_options.merge(all_options).delete_if do |key, value|
+        option_not_allowed?(key)
+      end
+    end
+
+    private
+
+    def template_can_capture?
+      template && template.respond_to?(:capture)
+    end
+
+    def captured_value
+      if template_can_capture?
+        captured_value_by_template
+      else
+        captured_return_value
+      end
+    end
+
+    def captured_value_by_template
+      template.capture(formatted_value, *block_arguments, &block)
+    end
+
+    def captured_return_value
+      block.call(formatted_value, *block_arguments)
+    end
+
+    def formatted_value
+      formatter.new(value, all_options, template, &block).to_s
+    end
+
+    def formatter
+      find_formatter || formatter_not_found
+    end
+
+    def formatter_not_found
+      raise "Couldn't find the #{as} formatter. Got: #{formatter_names.join(', ')}"
+    end
+
+    def formatter_names
+      self.class.formatters.map { |formatter| formatter.type.to_s }
+    end
+
+    def find_formatter
+      self.class.formatters.find { |formatter| formatter.type.to_s == as.to_s }
+    end
+
+    def option_not_allowed?(key)
+      if allowed_options.empty?
+        reserved_options.map(&:to_s).include?(key.to_s)
+      else
+        !allowed_options.map(&:to_s).include?(key.to_s)
+      end
+    end
+
+    def block_arguments
+      all_options[:block_arguments] || []
+    end
+
+    def as
+      all_options[:as] || View.default_formatter
+    end
+
+    def all_options
+      @options
+    end
+
+  end
+
+end
+
+Dir[File.expand_path('../formatters/*.rb', __FILE__)].each do |formatter_file|
+  require formatter_file
+end

data/lib/view/formatters/auto.rb

@@ -0,0 +1,49 @@
+module View
+
+  class Auto < Formatter
+
+    def to_s
+      if as
+        format
+      else
+        guess
+      end
+    end
+
+    def datetime_format?
+      value.respond_to?(:strftime)
+    end
+
+    def file_link_format?
+      View.file_methods.any? { |method| value.respond_to?(method) }
+    end
+
+    def boolean_format?
+      value == true || value == false
+    end
+
+    def nil_format?
+      value.nil?
+    end
+
+    def sentence_format?
+      value.respond_to?(:to_sentence)
+    end
+
+    def link_format?
+      all_options[:to]
+    end
+
+    def as
+      %w|nil boolean file_link datetime sentence link|.find { |type| send("#{type}_format?") }
+    end
+
+    def guess
+      View.guessing_methods.each do |method|
+        return value.send(method) if value.respond_to?(method)
+      end
+    end
+
+  end
+
+end

data/lib/view/formatters/boolean.rb

@@ -0,0 +1,19 @@
+module View
+
+  class Boolean < Formatter
+
+    def to_s
+      ::I18n.t(boolean_value.to_s, :scope => [:view, :booleans], :default => default)
+    end
+
+    def default
+      boolean_value ? "Yes" : "No"
+    end
+
+    def boolean_value
+      !!value
+    end
+
+  end
+
+end

data/lib/view/formatters/currency.rb

@@ -0,0 +1,13 @@
+module View
+
+  class Currency < Formatter
+
+    self.allowed_options = [ :precision, :unit, :separator, :delimiter, :format ]
+
+    def to_s
+      template.number_to_currency(value, options)
+    end
+
+  end
+
+end

data/lib/view/formatters/date.rb

@@ -0,0 +1,11 @@
+module View
+
+  class Date < Formatter
+
+    def to_s
+      ::I18n.l(value.to_date, options) if value.present?
+    end
+
+  end
+
+end

data/lib/view/formatters/datetime.rb

@@ -0,0 +1,11 @@
+module View
+
+  class Datetime < Formatter
+
+    def to_s
+      ::I18n.l(value, options) if value.present?
+    end
+
+  end
+
+end

data/lib/view/formatters/delimited.rb

@@ -0,0 +1,13 @@
+module View
+
+  class Delimited < Formatter
+
+    self.allowed_options = [ :separator, :delimiter ]
+
+    def to_s
+      template.number_with_delimiter(value, options)
+    end
+
+  end
+
+end

data/lib/view/formatters/file_link.rb

@@ -0,0 +1,33 @@
+module View
+
+  class FileLink < Formatter
+
+    self.reserved_options = [ :text, :text_method ]
+    self.default_options = { :target => "_blank" }
+
+    def to_s
+      template.link_to(text, path, options)
+    end
+
+    def path
+      View.path_methods.each do |method|
+        return value.send(method) if value.respond_to?(method)
+      end
+      nil
+    end
+
+    def text
+      all_options[:text] || text_via_method || value.to_s
+    end
+
+    def text_via_method
+      send(text_method) if text_method
+    end
+
+    def text_method
+      all_options[:text_method]
+    end
+
+  end
+
+end

data/lib/view/formatters/html_safe.rb

@@ -0,0 +1,11 @@
+module View
+
+  class HtmlSafe < Formatter
+
+    def to_s
+      value.to_s.html_safe
+    end
+
+  end
+
+end

data/lib/view/formatters/human.rb

@@ -0,0 +1,16 @@
+module View
+
+  # The number_to_human helper was introduced in Rails 3.
+  # It will give results like "10 thousand"
+  class Human < Formatter
+
+    self.allowed_options = [ :locale, :precision, :significant, :separator, :delimiter,
+      :strip_insignificant_zeros, :units, :format ]
+
+    def to_s
+      template.number_to_human(value, options)
+    end
+
+  end
+
+end

data/lib/view/formatters/image.rb

@@ -0,0 +1,37 @@
+module View
+
+  class Image < Formatter
+
+    self.reserved_options = [ :with ]
+
+    def to_s
+      template.image_tag(path, options) if file?
+    end
+
+    def path
+      value.send(path_method, *path_arguments)
+    end
+
+    # TODO I'm only guessing here, I don't actually know how other upload gems
+    # work, besides paperclip.
+    def path_method
+      View.path_methods.find { |method| value.respond_to?(method) }
+    end
+
+    # TODO with seems like a stupid name, but style is probably used for
+    # image_tag
+    def path_arguments
+      all_options[:with] || View.path_arguments
+    end
+
+    def file?
+      value.send(file_method)
+    end
+
+    def file_method
+      View.file_methods.find { |method| value.respond_to?(method) }
+    end
+
+  end
+
+end

data/lib/view/formatters/link.rb

@@ -0,0 +1,25 @@
+module View
+
+  class Link < Formatter
+
+    self.reserved_options = [ :to, :path, :text ]
+
+    def to_s
+      template.link_to(format, to, options)
+    end
+
+    def to
+      all_options[:to] || template.polymorphic_path(automatic_link)
+    end
+
+    def automatic_link
+      (all_options[:path] || []) + [ value ]
+    end
+
+    def as
+      all_options[:text] || :auto
+    end
+
+  end
+
+end

data/lib/view/formatters/nil.rb

@@ -0,0 +1,11 @@
+module View
+
+  class Nil < Formatter
+
+    def to_s
+      ::I18n.t(:nil, :scope => :view, :default => "")
+    end
+
+  end
+
+end

data/lib/view/formatters/percentage.rb

@@ -0,0 +1,13 @@
+module View
+
+  class Percentage < Formatter
+
+    self.allowed_options = [ :precision, :separator, :delimiter ]
+
+    def to_s
+      template.number_to_percentage(value, options)
+    end
+
+  end
+
+end

data/lib/view/formatters/phone.rb

@@ -0,0 +1,13 @@
+module View
+
+  class Phone < Formatter
+
+    self.allowed_options = [ :area_code, :delimiter, :extension, :country_code ]
+
+    def to_s
+      template.number_to_phone(value, options)
+    end
+
+  end
+
+end

data/lib/view/formatters/precision.rb

@@ -0,0 +1,13 @@
+module View
+
+  class Precision < Formatter
+
+    self.allowed_options = [ :precision, :separator, :delimiter ]
+
+    def to_s
+      template.number_with_precision(value, options)
+    end
+
+  end
+
+end

data/lib/view/formatters/self.rb

@@ -0,0 +1,11 @@
+module View
+
+  class Self < Formatter
+
+    def to_s
+      value
+    end
+
+  end
+
+end

data/lib/view/formatters/sentence.rb

@@ -0,0 +1,33 @@
+module View
+
+  class Sentence < Formatter
+
+    self.allowed_options = [ :words_connector, :two_words_connector, :last_word_connector ]
+
+    def to_s
+      if all_safe?
+        sentence.html_safe
+      else
+        sentence
+      end
+    end
+
+    def all_safe?
+      formatted_values.all? { |element| element.html_safe? }
+    end
+
+    def formatted_values
+      value.map { |element| View.to_s(element, each, template, &block) }
+    end
+
+    def sentence
+      formatted_values.to_sentence if value.present?
+    end
+
+    def each
+      all_options[:each] || { :as => View.default_formatter }
+    end
+
+  end
+
+end

data/lib/view/formatters/size.rb

@@ -0,0 +1,13 @@
+module View
+
+  class Size < Formatter
+
+    self.allowed_options = [ :precision, :separator, :delimiter ]
+
+    def to_s
+      template.number_to_human_size(value, options)
+    end
+
+  end
+
+end

data/lib/view/helper.rb

@@ -0,0 +1,11 @@
+module View
+
+  module Helper
+
+    def view(value, options = {}, &block)
+      ::View.to_s(value, options, self, &block)
+    end
+
+  end
+
+end

data/lib/view/railtie.rb

@@ -0,0 +1,13 @@
+module View
+
+  class Railtie < ::Rails::Railtie
+    
+    ActiveSupport.on_load(:action_view) do
+      ActiveSupport.on_load(:after_initialize) do
+        include Helper
+      end
+    end
+
+  end
+
+end

data/lib/view/version.rb

@@ -0,0 +1,3 @@
+module View
+  VERSION = '1.0.0.alpha.1'
+end

data/lib/view.rb

@@ -0,0 +1,29 @@
+module View
+
+  autoload :Formatter, 'view/formatter'
+  autoload :Helper,    'view/helper'
+  autoload :VERSION,   'view/version'
+
+  mattr_accessor :guessing_methods
+  self.guessing_methods = %w|to_label display_name full_name name title username login value to_s|
+
+  mattr_accessor :file_methods
+  self.file_methods = %w|mounted_as file? public_filename|
+
+  mattr_accessor :path_methods
+  self.path_methods = %w|mounted_as url public_filename|
+
+  mattr_accessor :path_arguments
+  self.path_arguments = []
+
+  mattr_accessor :default_formatter
+  self.default_formatter = :auto
+
+  mattr_accessor :formatters
+
+
+  def self.to_s(value, options = {}, template = nil, &block)
+    Formatter.to_s(value, options, template, &block)
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,22 @@
+require "rubygems"
+require "bundler/setup"
+Bundler.setup :default
+require 'active_support'
+require 'active_support/core_ext'
+require 'rspec'
+require 'view'
+
+module WithTranslation
+  def with_translation(keys)
+    locale = I18n.locale
+    I18n.backend.store_translations(:test, keys)
+    I18n.locale = :test
+    yield
+  ensure
+    I18n.locale = locale
+  end
+end
+
+RSpec.configure do |config|
+  config.include(WithTranslation)
+end

data/spec/view/formatters/auto_spec.rb

@@ -0,0 +1,25 @@
+require 'spec_helper'
+
+describe "Auto formatter" do
+
+  it "guesses the to_label" do
+    object = Struct.new(:to_label).new("some label")
+    View.to_s(object).should == "some label"
+  end
+
+  it "guesses to_s" do
+    object = Struct.new(:to_s).new("string")
+    View.to_s(object).should == "string"
+  end
+
+  it "guesses a name" do
+    object = Struct.new(:name).new("my name")
+    View.to_s(object).should == "my name"
+  end
+
+  it "guesses a login" do
+    object = Struct.new(:login).new("loginname")
+    View.to_s(object).should == "loginname"
+  end
+
+end

data/spec/view/formatters/boolean_spec.rb

@@ -0,0 +1,28 @@
+require 'spec_helper'
+
+describe "Boolean formatter" do
+
+  it "formats true" do
+    View.to_s(true).should == "Yes"
+  end
+
+  it "formats false" do
+    View.to_s(false).should == "No"
+  end
+
+  it "formats boolean values" do
+    View.to_s("h", :as => :boolean).should == "Yes"
+    View.to_s(nil, :as => :boolean).should == "No"
+  end
+
+  it "localizes booleans" do
+    with_translation :view => { :booleans => { :true => "yup" } } do
+      View.to_s(true).should == "yup"
+    end
+    with_translation :view => { :booleans => { :false => "nope" } } do
+      View.to_s(false).should == "nope"
+    end
+  end
+
+
+end

data/spec/view/formatters/date_spec.rb

@@ -0,0 +1,22 @@
+require 'spec_helper'
+
+describe "Date formatter" do
+
+  it "localizes dates" do
+    date = Date.new(2010, 10, 11)
+    with_translation :date => { :formats => { :foo => "%A" }, :day_names => [ "zondag", "maandag" ] } do
+      View.to_s(date, :format => :foo).should == "maandag"
+    end
+  end
+
+  it "formats dates" do
+    date = Date.new(2010, 10, 10)
+    View.to_s(date).should == "2010-10-10"
+  end
+
+  it "forces datetimes to date" do
+    time = Time.new(2010, 10, 10, 8, 45, 30, '+01:00')
+    View.to_s(time, :as => :date).should == "2010-10-10"
+  end
+
+end

data/spec/view/formatters/datetime_spec.rb

@@ -0,0 +1,17 @@
+require 'spec_helper'
+
+describe "Datetime formatter" do
+
+  it "formats" do
+    time = Time.new(2010, 10, 10, 8, 45, 30, '+01:00')
+    View.to_s(time).should == "Sun, 10 Oct 2010 08:45:30 +0100"
+  end
+
+  it "localizes" do
+    time = Time.new(2010, 10, 10, 8, 45, 30, '+01:00')
+    with_translation :time => { :formats => { :short => "%d-%m-%Y %H:%M" } } do
+      View.to_s(time, :format => :short).should == "10-10-2010 08:45"
+    end
+  end
+
+end

data/spec/view/formatters/nil_spec.rb

@@ -0,0 +1,15 @@
+require 'spec_helper'
+
+describe "Nil formatter" do
+
+  it "formats nil" do
+    View.to_s(nil).should == ""
+  end
+
+  it "uses i18n for nil" do
+    with_translation :view => { :nil => "nothing" } do
+      View.to_s(nil).should == "nothing"
+    end
+  end
+
+end

data/spec/view/formatters/self_spec.rb

@@ -0,0 +1,10 @@
+require 'spec_helper'
+
+describe "Self formatter" do
+
+  it "doesn't format with formatter self" do
+    time = Time.now
+    View.to_s(time, :as => :self).should == time
+  end
+
+end

data/spec/view/formatters/sentence_spec.rb

@@ -0,0 +1,10 @@
+require 'spec_helper'
+
+describe "Sentence formatter" do
+
+  it "constructs a sentence" do
+    object = [ 1, 2, 3 ]
+    View.to_s(object).should == "1, 2, and 3"
+  end
+
+end

data/spec/view/helper_spec.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+
+describe "View::Helper" do
+
+  pending "views" do
+    template = Class.new do
+      include View::Helper
+    end
+  end
+
+end

data/spec/view/view_spec.rb

@@ -0,0 +1,13 @@
+require 'spec_helper'
+
+describe "View" do
+
+  it "doesn't touch strings" do
+    View.to_s("bar").should == "bar"
+  end
+
+  it "parses the block" do
+    View.to_s("bar") { |val| val.upcase }.should == "BAR"
+  end
+
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification 
+name: view
+version: !ruby/object:Gem::Version 
+  prerelease: true
+  segments: 
+  - 1
+  - 0
+  - 0
+  - alpha
+  - 1
+  version: 1.0.0.alpha.1
+platform: ruby
+authors: 
+- Iain Hecker
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-10-03 00:00:00 +02:00
+default_executable: 
+dependencies: []
+
+description: A very extensible way of viewing objects, easily integrated with other gems
+email: 
+- iain@iain.nl
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- lib/view/formatter.rb
+- lib/view/formatters/auto.rb
+- lib/view/formatters/boolean.rb
+- lib/view/formatters/currency.rb
+- lib/view/formatters/date.rb
+- lib/view/formatters/datetime.rb
+- lib/view/formatters/delimited.rb
+- lib/view/formatters/file_link.rb
+- lib/view/formatters/html_safe.rb
+- lib/view/formatters/human.rb
+- lib/view/formatters/image.rb
+- lib/view/formatters/link.rb
+- lib/view/formatters/nil.rb
+- lib/view/formatters/percentage.rb
+- lib/view/formatters/phone.rb
+- lib/view/formatters/precision.rb
+- lib/view/formatters/self.rb
+- lib/view/formatters/sentence.rb
+- lib/view/formatters/size.rb
+- lib/view/helper.rb
+- lib/view/railtie.rb
+- lib/view/version.rb
+- lib/view.rb
+- init.rb
+- README.rdoc
+- spec/spec_helper.rb
+- spec/view/formatters/auto_spec.rb
+- spec/view/formatters/boolean_spec.rb
+- spec/view/formatters/date_spec.rb
+- spec/view/formatters/datetime_spec.rb
+- spec/view/formatters/nil_spec.rb
+- spec/view/formatters/self_spec.rb
+- spec/view/formatters/sentence_spec.rb
+- spec/view/helper_spec.rb
+- spec/view/view_spec.rb
+has_rdoc: true
+homepage: http://github.com/iain/view
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 3
+      - 6
+      version: 1.3.6
+requirements: []
+
+rubyforge_project: view
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Displaying objects automatically
+test_files: 
+- spec/spec_helper.rb
+- spec/view/formatters/auto_spec.rb
+- spec/view/formatters/boolean_spec.rb
+- spec/view/formatters/date_spec.rb
+- spec/view/formatters/datetime_spec.rb
+- spec/view/formatters/nil_spec.rb
+- spec/view/formatters/self_spec.rb
+- spec/view/formatters/sentence_spec.rb
+- spec/view/helper_spec.rb
+- spec/view/view_spec.rb