view 1.0.0.alpha.3 → 1.0.0.alpha.4

data/README.rdoc

@@ -2,79 +2,304 @@
 
 {Source}[http://github.com/iain/view] | {Documentation}[http://rubydoc.info/github/iain/view/master/frames]
 
-Automatic viewer. Very configurable. Very flexible. Very alpha (for now).
+View is a DSL to help you make default representations of objects. It's goal is not to add complex
+logic, but to help you make it really easy to display default elements.
 
-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!
+Some features:
 
-But first, the view!
+* View will automatically display your objects as you expect them to be.
+* View is smart about blank objects, so no more checking it in your views.
+* View contains many formatters, some really complex, and is very extensible.
+* View allows for exceptions by using the power of blocks.
+* View is designed to be short and looks at home in HAML.
+* Optional support for InheritedResources.
 
-== Usage
+This gem was inspired by {formtastic}[http://github.com/justinfrench/formtastic] and
+{simple_form}[http://github.com/plataformatec/simple_form]. It has been extracted from the helper
+methods I use regularly myself, but as a gem, View has still a long way to go.
 
-Use it from your views:
+== Installation
+
+Just add it to your Gemfile:
+
+  gem 'view'
+
+Run `bundle install` and you're ready to go!
+
+== Basic Usage
 
-  <%= view @post %>
+It' usually done through the `view` helper method.
+
+  = 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.
+View will automatically try to choose the proper formatter. The following will use I18n for
+formatting the time correctly:
 
-You can use view anywhere you like:
+  = view @post.created_at
 
-  puts View.format(@post)
+Normally I18n.localize will throw an exception if the value were to be nil, so you'd have to
+check for that yourself. View does this for you.
 
-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.
+You can specify a formatter yourself:
 
-== Options
+  = view @post.created_at, :as => :date
 
-View will automatically try to choose the proper formatter. You can specify a formatter yourself:
+You can add a block to specify your own behavior. The formatter is passed in as a block-variable.
+On the formatter the following methods are always available:
 
-  <%= view @post.created_at, :as => :date %>
+* `to_s` gets the formatted result
+* `value` gets the original value
+* `options` will return a (filtered) options hash, complete with defaults
 
-You can add a block to specify your own behavior. The formatter is passed in as a block-variable.
+Example:
 
-  <%= view @post.author do |formatter| %>
-    <%= link_to formatter.to_s, formatter.value %>
-  <% end %>
+  = view @post.author do |formatter|
+    = link_to formatter.to_s, backend_user_path(formatter.value)
 
-Most formatters pass their options down to the method they use, such as the image formatter:
+Most formatters pass their options down to the method they use, such as the date formatter:
 
-  <%= view @user.avatar, :as => :image, :size => "40x40", :class => "avatar" %>
+  = view @post.created_at, :format => :short
 
 == Examples
 
-There are many formatters included (18 and counting), but here are some interesting use cases of some of them.
+Now that we've got the basics down, let's continue with some more advanced examples.
+There are a lot of formatters that do very trivial things. This is because they are meant to be
+used inside other formatters. Let's start with some bigger formatters to give you an idea.
+
+=== Table
+
+You can render a table quite easily. If you're displaying a collection of ActiveRecord objects,
+it's even trivial:
+
+  = view @posts, :as => :table
+
+or even:
+
+  = table_for @posts
+
+This will display all columns, properly formatted, as you would expect. All columns might be a bit
+too much, so let's slim the table down:
+
+  = table_for @posts, :fields => [ :title, :author, :published_at ]
+
+Turn the titles into links:
+
+  = table_for @posts, :fields => [ :title, :author, :published_at ], :link => :title
+
+Ok, nice, but this is rather ugly. This list might get very long. Also, what if you want to
+control how certain columns are formatted? The solution is simple: use a block:
+
+  = table_for @posts do |table|
+
+    = table.view :title, :as => :link
+
+    = table.view :author do |formatter|
+      = link_to formatter.to_s, formatter.value
+
+    = table.view :published_at, :as => :date
+
+Now the power of the simple formatters can be fully appreciated.
+
+The table formatter will display a simple table. If you want to control what the table looks like,
+you can add a partial to your application in `app/views/shared/_table.html.haml` (or erb). Since
+this gem is a Rails 3 engine, it will automatically choose your own version over the one provided
+by this gem.
+
+One final note on tables: If you're using the gem
+{InheritedResources}[http://github.com/josevalim/inherited_resources], or something similar, you
+can just call `table` from the index view, and it will automatically use the collection.
+
+  = table
+
+See the {documentation}[http://rubydoc.info/github/iain/view/master/View/Table] for more
+information on tables.
+
+=== Definition lists
+
+You can generate definition lists in rather the same fashion as tables.
+Definition Lists are great for the show pages in a backend.
+
+On it's own:
+
+  = view @post, :as => :definition_list
+
+Or even:
+
+  = definition_list_for @post
+
+Or if you're using InheritedResources:
+
+  = definition_list
+
+You can also specify fields:
+
+  = definition_list_for @post, :fields => [ :title, :author ]
+
+And you can also use a block to go specific:
+
+  = definition_list_for @post do |dl|
+
+    = dl.view :title, :as => :link
+    = dl.view :author
+    = dl.view :published_on, :as => :date
+
+See the {documentation}[http://rubydoc.info/github/iain/view/master/View/DefinitionList] for more
+information on definition lists.
+
+=== Other formatters
+
+No we've seen the biggest formatters, let's look at some smaller ones.
+
+Some of these are longer than their regular Rails counterparts. In that case, remember that
+they can be easily used inside the table or definition list. Most of the common Rails helpers
+have been converted to formatters for that reason.
+
+==== Links
+
+Links can be quite easy:
+
+  = view @post, :as => :link
+
+You can provide options too:
+
+  = view @post, :as => :link, :method => :delete, :confirm => "are you sure?"
+
+And you can link to the specific versions of the page, using the awesome power of Rails'
+`polymorphic_path`.
+
+  = view @post, :as => :link, :path => [ :edit, :backend ]
 
-  # Options are passed to the helper methods:
-  view @post, :as => :link, :method => :delete, :confirm => "are you sure?"
+{Documentation}[http://rubydoc.info/github/iain/view/master/View/Link]
 
-  # Renders a link to the edit_page of the post:
-  view @post, :as => :link, :path => [ :edit ]
+==== Sentences
 
-  # Renders a sentence of links:
-  view Post.all, :each => { :as => :link }
+Create a simple sentence of an array, propery formatting each element:
 
-  # When using paperclip, renders the image:
-  view @project.logo, :as => :image
+  = view @post.tags, :as => :sentence
+
+Or even create a sentence of links:
+
+  = view @post.tags, :as => :sentence, :each => { :as => :link }
+
+{Documentation}[http://rubydoc.info/github/iain/view/master/View/Sentence]
+
+==== Images and file links
+
+There is also some support for uploaded files with paperclip.
+
+The following displays the user's (resized) avatar:
+
+  = view @user.avatar, :as => :image, :style => :thumbnail
+
+Or, if it isn't an image:
+
+  = view @project.document, :as => :file_link
+
+{Image Documentation}[http://rubydoc.info/github/iain/view/master/View/Image]
+{FileLink Documentation}[http://rubydoc.info/github/iain/view/master/View/FileLink]
+
+==== Booleans
+
+Booleans are automatically determined and converted into "Yes" and "No".
 
-  # Renders "yes" or "no" (with I18n support!)
   view @user.admin?
 
-See the formatters in lib/views/formatters to see their full documentation.
+You can change the text via I18n:
+
+  en:
+    view:
+      booleans:
+        'true': Yup
+        'false': Nope
+
+{Documentation}[http://rubydoc.info/github/iain/view/master/View/Boolean]
+
+==== Blank values
+
+Blank values are usually caught before any other formatter. So the Blank formatter can be used
+even if you chose another.
+
+So if the post hasn't been published, it will use the blank formatter.
+
+  = view @post.published_at
+
+Normally, the blank formatter doesn't output anything. You can change that by using I18n:
+
+  en:
+    view:
+      blank: "<em>~</em>"
+
+
+{Documentation}[http://rubydoc.info/github/iain/view/master/View/Blank]
+
+== Configuration
+
+There a lots of ways to configure the gem itself and individual formatters too! Let's go over
+the most important ones:
+
+The `guess` formatter looks for methods it considers to be safe to display. The default list is
+
+* `to_label`
+* `display_name`
+* `full_name`
+* `title`
+* `username`
+* `login`
+* `value`
+* `to_s`
+
+It will use the first one it can find. If you want to add a method to that list, you can add
+a file in your initializers and write:
+
+  View.configure do |config|
+    config.guessing_methods = [ :my, :own, :methods ]
+  end
+
+If you wrote your own formatter that you would rather use, instead of the `auto` formatter:
+
+  View.configure do |config|
+    config.default_formatter = :my_own_formatter
+  end
+
+There is also a default formatter for arrays, which you can change like this:
+
+  View.configure do |config|
+    config.default_list_formatter = :sentence
+  end
+
+{Configuration}[http://rubydoc.info/github/iain/view/master/View/Configuration]
+
+You might have a special object, that you want to be rendered with your favorite formatter.
+You can let the auto formatter know about it. Say you want to display all numbers as delimited
+values (using the `number_with_delimiter` helper from Rails):
+
+  View::Auto.add :delimited do
+    value.is_a?(Fixnum)
+  end
+
+{Auto formatter}[http://rubydoc.info/github/iain/view/master/View/Auto]
+
+You can also customize formatters default options. To change every unit in currency,
+you can use this:
+
+  View::Currency.default_options = { :unit => "Cubits", :format => "%n %s" }
+
+Remember that the Rails number formatters can also be configured using I18n.
 
 == Adding formatters
 
-You can add a formatter by inheriting from +View::Formatter+.
-The only method you need to implement is the +format+ method.
+You can add a formatter by inheriting from `View::Formatter`.
+The only method you need to implement is the `format` 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
+* `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:
 
@@ -88,7 +313,7 @@ If you wanted a uppercase formatter for example, you could do this:
 
 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.
+You can use the `.as` method to specify a different name.
 
   class Foo < View::Formatter
     as :bar
@@ -102,7 +327,7 @@ You can control which options are allowed, by adding reserved options:
   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.
+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
@@ -122,22 +347,15 @@ To more tightly control which options are allowed, specify the allowed options:
 
 You can use the existing formatters as examples.
 
-== Configuration:
-
-See +lib/view.rb+ for information on configuration.
-
-== Installation
-
-Just add it to your Gemfile:
-
-  gem 'view'
-
-Run +bundle install+ and you're ready to go!
+{Documentation}[http://rubydoc.info/github/iain/view/master/View/Formatter]
 
 == Contributing
 
 Yes please! You know the drill: fork, commit, pull request, profit!
 
+I'm especially interested in ideas for formatters and new use cases.
+Use the {issue tracker}[http://github.com/iain/view/issues] to let me know!
+
 == License
 
 Copyright 2010 Iain Hecker (iain@iain.nl), released under the MIT License.

data/lib/view/configuration.rb

@@ -0,0 +1,55 @@
+module View
+
+  # The central place for all configuration.
+  class Configuration
+
+    # Used by the guess filter, these are the methods used to format an object.
+    # It will use the first method that the object responds to.
+    attr_accessor :guessing_methods
+
+    # To determine if something is an uploaded image, it checks
+    # to see whether it responds to one of these methods.
+    attr_accessor :file_methods
+
+    # To show an image, it will use one of these methods to get the src
+    # attribute.
+    attr_accessor :path_methods
+
+    # You can set a default argument for rendering images, like the style or size
+    # of the image. It will be passed to one of the path_methods.
+    attr_accessor :path_arguments
+
+    # Which formatter will be used by default. The default is auto, which does
+    # all sorts of interesting stuff to see what to do.
+    attr_accessor :default_formatter
+
+    # The auto formatter will choose this formatter by default when your value is
+    # an array (or really, something that responds to +each+).
+    attr_accessor :default_list_formatter
+
+    # Shorthand for configuring this gem.
+    #
+    # @example In +config/initializers/view.rb+
+    #
+    #   View.configure do |config|
+    #     config.default_formatter = :self
+    #   end
+    #
+    # @yield [config] The View module
+    def configure
+      yield self
+    end
+
+    def initialize
+      self.guessing_methods       = %w|to_label display_name full_name name title
+                                       username login value to_s|
+      self.file_methods           = %w|file? mounted_as public_filename|
+      self.path_methods           = %w|url mounted_as public_filename|
+      self.path_arguments         = []
+      self.default_formatter      = :auto
+      self.default_list_formatter = :sentence
+    end
+
+  end
+
+end

data/lib/view/formatter.rb

@@ -9,7 +9,7 @@ module View
     self.default_options = {}
 
     class_inheritable_array :reserved_options
-    self.reserved_options = [ :as, :block_arguments ]
+    self.reserved_options = [ :as ]
 
     class_inheritable_array :allowed_options
     self.allowed_options = []
@@ -47,7 +47,7 @@ module View
 
     # By default, blank values (nil, empty strings, etc), will override any
     # formatter you specified. This way empty values are handled globally.
-    # 
+    #
     # If you don't want this, you can either turn it off per formatter.
     # Call this method to turn it off.
     #
@@ -81,7 +81,7 @@ module View
     # It's generally a good idea to black list options that you use inside your
     # formatter.
     #
-    # The options +:as+ and +:block_arguments+ are black listed by default.
+    # The option +:as+ is black listed by default.
     #
     # @example White listing:
     #
@@ -148,7 +148,7 @@ module View
     end
 
     def self.formatters
-      View.formatters ||= []
+      View.formatters
     end
 
     def initialize(value, options = {}, template = nil, &block)
@@ -160,7 +160,7 @@ module View
 
     def formatted_value
       formatter_not_found unless formatter
-      formatter.new(value, all_options, template, &block).format!
+      formatter.new(value, all_options, template, &block).send(:format!)
     end
 
     def template_can_capture?
@@ -176,11 +176,11 @@ module View
     end
 
     def captured_value_by_template
-      template.capture(self, *block_arguments, &block)
+      template.capture(self, &block)
     end
 
     def captured_return_value
-      block.call(self, *block_arguments)
+      block.call(self)
     end
 
     def formatter
@@ -204,12 +204,8 @@ module View
       end
     end
 
-    def block_arguments
-      all_options[:block_arguments] || []
-    end
-
     def as
-      all_options[:as] || View.default_formatter
+      all_options[:as] || View.configuration.default_formatter
     end
 
     def blank_formatter

data/lib/view/formatters/array.rb

@@ -27,7 +27,7 @@ module View
     end
 
     def each_options
-      all_options[:each] || { :as => View.default_formatter }
+      all_options[:each] || { :as => View.configuration.default_formatter }
     end
 
   end

data/lib/view/formatters/auto.rb

@@ -43,7 +43,7 @@ module View
       as ? as[:formatter] : :guess
     end
 
-    add View.default_list_formatter do
+    add View.configuration.default_list_formatter do
       value.respond_to?(:each)
     end
 
@@ -52,13 +52,17 @@ module View
     end
 
     add :file_link do
-      View.file_methods.any? { |method| value.respond_to?(method) }
+      View.configuration.file_methods.any? { |method| value.respond_to?(method) }
     end
 
     add :link do
       all_options.has_key?(:to)
     end
 
+    add :self do
+      value.is_a?(String)
+    end
+
     add :blank do
       value.blank?
     end

data/lib/view/formatters/definition_list.rb

@@ -0,0 +1,110 @@
+module View
+
+  # Creates a simple definition list for an object.
+  # This works well with ActiveRecord objects.
+  # Without a block it will render all fields. You can specify the fields
+  # using the `fields` option.
+  #
+  # You can use a block, to further format the way the definition items are
+  # formatted.
+  #
+  # @example Without a block
+  #
+  #   = view @post, :as => :definition_list, :fields => [ :title, :author ]
+  #
+  # @example With a block
+  #
+  #   = view @post, :as => :definition_list do |dl|
+  #     = dl.view :title
+  #     = dl.view :author
+  #     = dl.view :published_at, :as => :date
+  #
+  class DefinitionList < Formatter
+
+    self.reserved_options = [ :fields ]
+
+    # This will add the dt and dd tags.
+    #
+    # @param [Symbol] attribute The name of the attribute to be called on +value+
+    # @param [Hash] options These will be delegated to the formatting of the
+    #   attribute's value.
+    # @yield [formatter] The block will be used for formatting the attribute's
+    #   value
+    def view(attribute, options = {}, &block)
+      tag = Attribute.new(value, attribute, block, template, options)
+      tag.dt + tag.dd
+    end
+
+    protected
+
+    def format!
+      template.content_tag(:dl, super, options)
+    end
+
+    def format
+      unless block
+        fields.inject("".html_safe) do |html, field|
+          html << view(field)
+        end
+      end
+    end
+
+    def fields
+      all_options[:fields] || all_fields
+    end
+
+    private
+
+    def all_fields
+      value_class.respond_to?(:column_names) ? value_class.column_names : []
+    end
+
+    def value_class
+      value.class
+    end
+
+    # Helper class for definition lists
+    class Attribute < Struct.new(:resource, :attribute, :block, :template, :options)
+
+      def dt
+        tag :dt, name
+      end
+
+      def dd
+        tag :dd, value
+      end
+
+      private
+
+      def tag(type, value)
+        template.content_tag(type, value, html_options)
+      end
+
+      def name
+        if klass.respond_to?(:human_attribute_name)
+          klass.human_attribute_name(attribute)
+        else
+          attribute.to_s.titleize
+        end
+      end
+
+      def klass
+        resource.class
+      end
+
+      def value
+        View.format(original_value, options, template, &block)
+      end
+
+      def original_value
+        resource.send(attribute)
+      end
+
+      def html_options
+        { :class => attribute }
+      end
+
+    end
+
+  end
+end

data/lib/view/formatters/file_link.rb

@@ -25,7 +25,7 @@ module View
     end
 
     def path
-      View.path_methods.each do |method|
+      View.configuration.path_methods.each do |method|
         return value.send(method) if value.respond_to?(method)
       end
       nil

data/lib/view/formatters/guess.rb

@@ -3,11 +3,11 @@ module View
   # This formatter is the fallback formatter for auto. It figures out which
   # method will be called to get a proper version to render.
   #
-  # @see View.guessing_methods
+  # @see View::Configuration#guessing_methods
   class Guess < Formatter
 
     def format
-      View.guessing_methods.each do |method|
+      View.configuration.guessing_methods.each do |method|
         return value.send(method) if value.respond_to?(method)
       end
       value

data/lib/view/formatters/human.rb

@@ -2,6 +2,7 @@ module View
 
   # The number_to_human helper was introduced in Rails 3.
   # It will give results like "10 thousand"
+  # @see http://rubydoc.info/docs/rails/3.0.1/ActionView/Helpers/NumberHelper:number_to_human
   class Human < Formatter
 
     self.allowed_options = [ :locale, :precision, :significant, :separator, :delimiter,