Mange-field_helpers 1.0.1

data/History.rdoc

@@ -0,0 +1,7 @@
+= History
+
+== Release 1.0.1
+* Added default options for FieldHelpers::Base. You can now do some cool stuff with this.
+
+== Release 1.0.0
+* Initial release

data/README.rdoc

@@ -0,0 +1,240 @@
+= FieldHelpers
+
+== Informal introduction
+Let's play a little mind game here:
+
+You are to build a Rails application which is very data heavy. The client wants many views with much data displayed on each.
+Many of these data fields are optional so they can be nil sometimes. You want the app to be translatable with <tt>I18n</tt>.
+
+Here is the icing on the cake: Many of the fields require special formatting.
+
+Sounds tiresome? Indeed it would be -- if you didn't have FieldHelpers installed!
+
+<b>Tell me more</b>
+
+Even if you don't have it as bad as in the imagined (I wish) scenario above, you could get a productivity boost from using
+FieldHelpers. Many apps need to display values and many apps have optional values, so it makes sense to have helpers for doing this.
+
+<b>Okay, so I define a little helper. Big deal?</b>
+
+Well, it's not as simple as that all the time. Some features are hard to build right and even more features require a lot of code to
+get to work.
+
+You could solve the optional field problem by checking for nil:
+  def field(record, field)
+    (v = record.send(field)) ? v : ""
+  end
+
+Okay, now add custom formatting, value conversion, field kind discovery, i18n capabilities and... a understanding of associations.
+Yeah, not so tough anymore, are you?
+
+<b>Wait, what? Conversion? Discovery? What is this?</b>
+
+Didn't I tell you? FieldHelpers handles different kinds of fields differently. Look at this example:
+  field_value(@user, :name)                       # => "John Doe"
+  field_value(@user, :name, :format => "Mr. %s")  # => "Mr. John Doe"
+  field_value(@user, :pay, :kind => :money)       # => "$1,000.00"
+  field_value(@user, :active?)                    # => "Yes"
+  field_value(@user, :group)                      # => "<a href=\"/groups/14\">Administrators</a>"
+  field_value(@user, :created_at, :kind => :time) # => "13:45:02"
+  field_value(@user, :created_at, :kind => :date) # => "2007-02-14"
+  field_value(@user, :created_at)                 # => "2007-02-14 13:45:02 +0100"
+
+<b>Holy crap!</b>
+
+No, this is not crap. It can do a lot more! See the association example above? The group link? It contains a lot of logic.
+You can customize the text, path, add classes, and so on. Use it to build your own helpers!
+
+  def user_field(record, field = :user)
+    field(record, field, :link_options => {:class => 'user'}, :link_field => :full_name)
+  end
+  
+  user_field(@comment, :author)
+  # => "<div class=\"field\"><strong>Author</strong> <a href=\"/users/13\" class=\"user\">Edward von Edenburgh</a></div>"
+
+It will try to find the text by looking at a few options you specify, and then by looking to see if the model responds to a few methods
+like "name", "title" and so on. If everything fails, the record in question will just be converted to a string.
+
+You can also do self-links. Say that you are doing a table of associated record: (This is a complex example!)
+
+  - @user.comments.each do |comment|
+    %tr
+      %td= field_value(comment, :title, :kind => :link, :link_path => post_comments_path(comment.post, comment))
+      %td= field_value(comment, :post)
+      %td= field_value(comment, :approved?)
+      %td= field_value(comment, :created_at)
+
+The first cell will now contain a link to the comment in question with the text in the "title" attribute of the comment. The path will be
+a nested resource path that had nothing to do with the current view. If there was a chance of comment being nil, we could even have wrapped
+the link_path option in a lambda and we would not get any errors at all.
+
+The second cell would contain a link to the post. field_value can figure out how to handle this association all by itself. Sexy! As you can
+see, using the link functionality is very easy!
+
+<b>Gimme! How do I install it?</b>
+
+Install it like any other gem from GitHub:
+  $> gem source -a http://gems.github.com
+  $> sudo gem install Mange-field_helpers
+  
+Then add it as a gem in your <tt>environment.rb</tt>:
+  config.gem "Mange-field_helpers", :lib => 'field_helpers', :source => 'http://gems.github.com'
+  
+== Features
+You get two helpers: <tt>field</tt> and <tt>field_value</tt>. Use them for displaying values in your application.
+* <tt>field_value</tt>
+  * Doesn't fail if the value is nil
+  * Discovers what kind of field it is by looking at the field name and/or value
+  * Formats the field from rules depending on the kind
+  * Returns sane default values when value was nil or an empty string
+    * Returns <tt>Model.human_attribute_name('no_name')</tt> when 'name' field is empty, for example
+    * Returns empty string if option <tt>:no_blanks</tt> is set
+  * Can use an additional custom format for even more fine-grained formatting in certain situations
+  * Can be extended with even more kinds
+    * Discovery is easy to extend
+    * Formatting is very easy to improve
+  * Can in theory be used outside views (but why would you want to? Sounds like a bad idea to me)
+* <tt>field</tt>
+  * Uses <tt>field_value</tt> to get value
+  * Uses <tt>human_attribute_name</tt> (I18n support!) of the model to get field name
+  * Wraps it all in easy-to-style elements for you to use
+
+The methods have a full test suite and most of the methods are very, very short.
+
+== Example
+Let's take the example from earlier and show how to do it without the helpers. That is a good example!
+Note that we use Haml since ERB disgusts me. Haml is not required.
+
+<b>With FieldHelpers:</b>
+
+ = field @user, :name
+ = field @user, :name, :format => "Mr. %s"
+ = field @user, :pay, :kind => :money
+ = field @user, :active?
+ = field @user, :group
+ = field @user, :created_at, :kind => :time
+ = field @user, :created_at, :kind => :date
+ = field @user, :created_at
+
+<b>Without FieldHelpers:</b>
+
+ .field
+   %strong= User.human_attribute_name('name')
+   - if @user.name
+     = @user.name
+   - else
+     = User.human_attribute_name('no_name')
+  
+ .field
+   %strong= User.human_attribute_name('name')
+   - if @user.name
+     == Mr. #{@user.name}
+   - else
+     = User.human_attribute_name('no_name')
+  
+ .field
+   %strong= User.human_attribute_name('pay')
+   - if @user.pay
+     = number_to_currency(@user.pay)
+   - else
+     = User.human_attribute_name('no_pay')
+  
+ .field
+   %strong= User.human_attribute_name('active?')
+   - unless @user.active?.nil?
+     = @user.active? ? I18n.translate(:yes) : I18n.translate(:no)
+   - else
+     = User.human_attribute_name('no_active?')
+  
+ .field
+   %strong= User.human_attribute_name('group')
+   - if @user.group
+     = link_to @user.group.name, @user.group
+   - else
+     = User.human_attribute_name('no_group')
+  
+ .field
+   %strong= User.human_attribute_name('created_at')
+   - if @user.created_at
+     = @user.created_at.to_time.to_s(:time)
+   - else
+     = User.human_attribute_name('no_created_at')
+  
+ .field
+   %strong= User.human_attribute_name('created_at')
+   - if @user.created_at
+     = @user.created_at.to_date.to_s
+   - else
+     = User.human_attribute_name('no_created_at')
+  
+ .field
+   %strong= User.human_attribute_name('created_at')
+   - if @user.created_at
+     = @user.created_at
+   - else
+     = User.human_attribute_name('no_created_at')
+  
+
+Now, tell me which one you want to maintain.
+
+== Registering your own kinds
+As I have mentioned earlier, you can register your own kinds. Just call <tt>FieldHelpers::Base.register_kind</tt>
+and you'll be on your way to world domination. Here are some silly examples of this:
+
+=== Adding the kinds themselves
+  
+  # Method 1: Using procs
+  FieldHelpers::Base.register_kind(:title, 
+      lambda { |base|
+        base.original_value.to_s.titleize
+      }
+  )
+  
+  # Method 2: Using other methods
+  
+  # In lib/field_extensions.rb
+  class FieldExtensions
+    def convert_password(base)
+       if base.options[:password_full]
+         base.original_value.gsub(/./, '*')
+       else
+         "************"
+       end
+    end
+  end
+  
+  # Then, wherever you want to. In an initializer, perhaps?
+  FieldHelpers::Base.register_kind(:password, FieldExtensions.method(:convert_password))
+  
+After doing this, you can display them by specifying kind as either <tt>:password</tt> or <tt>:title</tt>. You can also
+overwrite defaults kinds this way if you want.
+
+=== Adding auto-discovery of kinds
+In a much similar way as adding the helper methods, you can add methods to discover kinds.
+
+  # Method 1: Using procs
+  FieldHelpers::Base.register_kind_discovery(:title, 
+      lambda { |field, value|
+        true if field =~ /title$/
+      }
+  )
+  
+  # Method 2: Using blocks
+  FieldHelpers::Base.register_kind_discovery(:title) do |field, value| 
+    true if field =~ /title$/
+  end
+  
+  # Method 3: Using other methods
+  
+  # In lib/field_extensions.rb
+  class FieldExtensions
+    def discover_password(field, value)
+      true if field == :password
+    end
+  end
+  
+  # Then, wherever you want to. In an initializer, perhaps?
+  FieldHelpers::Base.register_kind_discovery(:password, FieldExtensions.method(:discover_password))
+
+You can turn of auto-discovery for certain kinds this way!
+  FieldHelpers::Base.register_kind_discovery(:email, lambda { false })

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:minor: 0
+:patch: 1
+:major: 1

data/lib/field_helpers.rb

@@ -0,0 +1,50 @@
+# Copyright (c) 2008
+#   * Magnus Bergmark
+# 
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+# 
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+# 
+
+# Main module for everything related to the field helpers. By requiring this file,
+# +ActionView+ will be extended with the methods in <tt>FieldHelpers::Helper</tt>.
+#
+# Most probably, the methods in <tt>FieldHelpers::Helper</tt> are the methods you are
+# interested in reading. Here's a small shortcut:
+# * <tt>FieldHelpers::Helper.field</tt>
+# * <tt>FieldHelpers::Helper.field_value</tt>
+module FieldHelpers
+end
+
+require 'field_helpers/base'
+require 'field_helpers/kinds'
+require 'field_helpers/helper'
+
+# Register the default kinds
+FieldHelpers::Kinds.available_kinds_with_helpers.each_pair do |kind, method|
+  FieldHelpers::Base.register_kind(kind, method)
+end
+
+FieldHelpers::Kinds.available_kinds_with_discoverers.each_pair do |kind, method|
+  FieldHelpers::Base.register_kind_discovery(kind, method)
+end
+
+# Add the helpers to all views
+ActionView::Base.class_eval do
+  include FieldHelpers::Helper
+end

data/lib/field_helpers/base.rb

@@ -0,0 +1,179 @@
+# Copyright (c) 2008
+#   * Magnus Bergmark
+# 
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+# 
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+# 
+
+# Instances of this class will be passed around between all the helper methods to ease the
+# options handling. This class takes values when being initialized and then parses and stores
+# them in attributes. It has some virtual attributes that you should check out, too.
+#
+# Instances of this class is often referred to as <tt>base</tt>s.
+class FieldHelpers::Base
+
+  # The registered helper methods will be saved in this hash. The key will be a kind symbol
+  # and the actual value will be a proc.
+  cattr_accessor :kind_helpers
+  
+  # The registered kind discoverers will be saved in this hash. The key will be a kind symbol
+  # and the actual value will be a proc.
+  cattr_accessor :kind_discoverers
+  
+  # Contains the default options that the explicit options will be merged with.
+  #
+  # Tip: Disable kind auto-discovery by setting <tt>:kind</tt> to <tt>:string</tt> here.
+  cattr_accessor :default_options
+  self.default_options = {}
+  
+  class << self
+    
+    # Register a kind for the helper methods. Specify the kind name as a symbol and then give
+    # a proc for the helper as the second parameter. It is recommended that you use the <tt>method</tt>
+    # method to get a method from a class as a proc.
+    #
+    # Example:
+    #   FieldHelpers::Base.register_kind(:funky, FunkyHelpers.method(:render_funky))
+    #   FieldHelpers::Base.register_kind(:small, lambda { |b| b.original_value.downcase })
+    #
+    # Please see docs for FieldHelpers::Kinds for information about how these methods are to be
+    # built and how to use them.
+    #
+    def register_kind(kind_name, helper_proc)
+      self.kind_helpers ||= {}
+      self.kind_helpers[kind_name.to_sym] = helper_proc
+    end
+    
+    # Register a kind for the discover methods. Specify the kind name as a symbol and then give
+    # a proc for the discoverer as the second parameter (or provide a block). It is recommended
+    # that you use the <tt>method</tt> method to get a method from a class as a proc.
+    #
+    # Example:
+    #   FieldHelpers::Base.register_kind_discovery(:funky, FunkyHelpers.method(:field_is_funky?))
+    #   FieldHelpers::Base.register_kind_discovery(:title, lambda { |f,v| true if f =~ /title/ })
+    #   FieldHelpers::Base.register_kind_discovery(:complex) do |field, value|
+    #     # ...
+    #   end
+    #
+    # Please see docs for FieldHelpers::Kinds for information about how these methods are to be
+    # built and how to use them.
+    #
+    def register_kind_discovery(kind_name, discovery_proc = nil, &block)
+      self.kind_discoverers ||= {}
+      raise ArgumentError, "You must specify a proc or block" if discovery_proc.nil? and not block_given?
+      
+      self.kind_discoverers[kind_name.to_sym] = (block_given? ? block : discovery_proc)
+    end
+    
+    # Calls the registered discoverers to find out the kind of a given field name and value. If no
+    # discoverer returns <tt>true</tt>, a kind of <tt>:string</tt> is assumed.
+    #
+    # Note: The order of the discoverers calls are not guranteed or known.
+    def discover_kind(field, value)
+      self.kind_discoverers.each_pair do |kind, method|
+        return kind if method.call(field.to_s, value) == true # Require an explicit TrueClass
+      end
+      return :string # Default to string
+    end
+  end
+  
+  # This holds a reference to the template context in which the text is about to be rendered. If you
+  # want to use any methods present in views, just call them through this variable.
+  #
+  # Example:
+  #   template.content_tag(:div, "Hello World")
+  attr_accessor :template
+  
+  # This is a reference to the record (aka. model) being used.
+  attr_accessor :record
+  
+  # This is a symbol representing the field given to the helpers.
+  attr_accessor :field
+  
+  # This is a copy of the options hash that was passed to the helpers.
+  attr_accessor :options
+  
+  # This is the original value before any convertions and similar. It could be nil.
+  # The value is worked out by asking the record for the value of the method specified in field.
+  def original_value
+    return @original_value if @original_value
+    @original_value = record.send(field) if record.respond_to? field
+  end
+  
+  # A virtual attribute that wraps some logic around the handling of empty original values. If the
+  # original_value is nil or an empty string, default_value will be returned instead.
+  #
+  # If the original_value was not empty, the method will try to guess the kind and then convert it
+  # to that kind before returning it.
+  #
+  # This method will raise an ArgumentError if there is no helper for the specified/discovered kind.
+  def value
+    return @value if @value
+    @value = original_value
+    # false will be considered #blank? == true, which is not intended
+    if @value.nil? or @value == ""
+      @value = default_value 
+    else
+      method = kind_helpers[kind]
+      raise ArgumentError, "Unknown kind: #{kind}" if method.nil?
+      @value = method.call(self)
+    end
+    @value
+  end
+  
+  # Returns the default value, aka. what to display if the field is nil or empty. If no <tt>:default</tt>
+  # option has been specified, and blank values are to be displayed, this will be the human attribute
+  # name <tt>no_<field></tt> where <tt><field></tt> is the field name.
+  #
+  # If <tt>:no_blanks</tt> is specified, this method will always return an empty string.
+  def default_value
+    if options[:default]
+      options[:default]
+    elsif options[:no_blanks]
+      ""
+    else
+      record.class.human_attribute_name("no_#{field}", :default => [:blank_field_value, ""])
+    end
+  end
+  
+  # Returns the specified kind, or tries to discover the kind from the field name and value. This method
+  # is memoized so the discovery will not be done multiple times.
+  def kind
+    @kind ||= options[:kind] || FieldHelpers::Base.discover_kind(field, original_value)
+  end
+  
+  # Creates a new "base field". This contains the given options and attributes and provides convenience
+  # methods to make everything easier.
+  def initialize(template, record, field, options={})
+    self.template       = template
+    self.record         = record
+    self.field          = field
+    self.options        = default_options.merge(options)
+  end
+  
+  # A small wrapper around <tt>value</tt>. This method takes care of custom formatting and might in the future
+  # also take care of some form of filtering and escaping.
+  def value_for_view
+    unless record.nil?
+      format = options[:format] || "%s"
+      format % value
+    end
+  end
+
+end