Mange-field_helpers 1.0.1

data/lib/field_helpers/helper.rb

@@ -0,0 +1,203 @@
+# 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.
+# 
+
+# The methods defined here will be included in all views as helpers. Read the documentation
+# for each of them to get a good understanding of how everything works.
+module FieldHelpers::Helper
+
+  #
+  # Returns a rendering of a specific field from a given record.
+  #
+  # == Features
+  # * Display translated field name
+  # * Display view-friendly variants of values
+  #   * Email adresses as <tt>mail_to</tt> links
+  #   * Money as <tt>number_to_currency</tt> dictates
+  #   * nil and blank values behave differently, but safely
+  #   * And more!
+  # * Consistent markup
+  #
+  # == Value
+  # The logic behind the value being displayed is passed off to <tt>field_value</tt>. See documentation for
+  # <tt>field_value</tt> for more information about that.
+  #
+  # Before being used, the resulting value will also be passed through <tt>simple_format</tt>, which will
+  # convert newlines and paragraph breaks into their proper html elements.
+  #
+  # == Title / Label / Field name
+  # By default, the field name will be whatever the record says it should be through <tt>human_attribute_name</tt>,
+  # but you can customize this by giving a translation key to the <tt>:title</tt> option.
+  #
+  # == Visibility
+  # When the value is blank and <tt>:no_blanks</tt> option is set to true, nothing will be returned from this helper.
+  # This is useful for displaying a huge bunch of optional fields where most of them will not be entered,
+  # since only those with actual values will take space on the view.
+  #
+  # The <tt>:no_blanks</tt> option will be passed on to the <tt>field_value</tt> helper, so the fallback translation values
+  # will not be used.
+  #
+  def field(record, field, options = {})
+    no_blanks = options[:no_blanks]
+    title = options.delete(:title)
+    
+    label = I18n.translate(title) if title
+    label ||= record.class.human_attribute_name(field.to_s)
+    
+    value = field_value(record, field, options)
+    
+    # If no_blanks is set, we should not output anything if the value is empty
+    return "" if no_blanks and value.blank?
+    
+    formatted_value = simple_format(value)
+    content_tag(:div, "#{content_tag(:strong, label)}#{formatted_value}", :class => 'field')
+  end
+  
+  #
+  # Returns a view-friendly representation of a record's field value.
+  #
+  # == Friendly representation
+  # Sometimes you want to display an optional value on a page, so you need to think about the event of
+  # the value being nil. Now, if you want to display a placholder for the nil value, you'll have to place
+  # a conditional in your view, which clutters and adds complexity. By using this helper, you can avoid
+  # situations like these.
+  #
+  # If the field you specify is nil or empty the first working variant of a placeholder will be displayed
+  # instead:
+  # * Model.human_attribute_name("no_field_name")
+  # * I18n.translate(:"activerecord.attributes.blank_field_value")
+  # * "" (Empty string)
+  #
+  # Now, this is a lot easier to handle on a per-case basis. If you want to always display an empty value
+  # instead of looking for the translations, you can do so by passing the <tt>:no_blanks</tt> option.
+  #
+  # == Special value kinds
+  # Some fields need special treatment. It could be a field containing money values which you want to be
+  # formatted correctly. It could be that you want the date component from a DateTime. You could want a
+  # simple "Yes" or "No" for a boolean.
+  #
+  # You can do this be specifying the <tt>:kind</tt> parameter (or relying on the auto-detection). The following
+  # kinds are supported:
+  # [<tt>:money</tt>]       Value is passed through number_to_currency. Auto-discovered when field name contains
+  #                         "price" or "amount".
+  #
+  # [<tt>:email</tt>]       Value is passed through mail_to. Auto-discovered when field name is "email".
+  #
+  # [<tt>:date</tt>]        Value is casted to date and then to string. Effectivly displaying only the date component
+  #                         of any date-like value. Autodiscovered when field name ends with "_on" or value is a
+  #                         Date object.
+  #
+  # [<tt>:time</tt>]        Value is casted to time and then to a formatted string following the template <tt>:time</tt>.
+  #                         This removes anything but the hour, minute and second from the value. Never auto-
+  #                         discovered.
+  #
+  # [<tt>:datetime</tt>]    Value is being casted to a time and then directly to a string. Auto-discovered when field
+  #                         name ends with "_at" or value is a Time or TimeWithZone object.
+  #
+  # [<tt>:bool</tt>]        Value will be a translation of the key <tt>:yes</tt> or <tt>:no</tt> depending on whether or not the
+  #                         value evaluates to true. Auto-discovered when the field name ends with a question mark or
+  #                         if the value is an explicit <tt>true</tt> or <tt>false</tt>.
+  #
+  # [<tt>:link</tt>]        This is pretty special. See section about it below. Auto-discovered when value is a kind
+  #                         of ActiveRecord::Base.
+  #
+  # == Links
+  # You can get actual links from using this helper. This is very useful for displaying associations that can
+  # be nil. If you set the kind to <tt>:link</tt> this specific logic will kick in. If there is an active association
+  # in the specified field (e.g. <tt>record.field</tt> is not <tt>nil</tt>) a link to the value will be generated.
+  #
+  #   field_value(@order_item, :order, :kind => :link) # => "<a href=\"/orders/1\">Order One</a>"
+  #
+  # === Self-links
+  # You can also use this to get a link to the object itself. If the field does not contain an ActiveRecord it
+  # is assumed that you want a self-link. The text of the link will then be assigned to the field specified and
+  # the target to the object itself.
+  #
+  #   field_value(@user, :full_name, :kind => :link) # => "<a href=\"/users/532\">Kevin Bacon</a>"
+  #
+  # In the case above, the following could be seen as equivalent if @order has a user attribute:
+  #
+  #   field_value(@order, :user, :link_field => :full_name)
+  #   # => "<a href=\"/users/532\">Kevin Bacon</a>"
+  #
+  # === Link text
+  # The link text will be genrated from the first option that is not evaluated to false:
+  # * Text of the <tt>:link_text</tt> option
+  # * The field name specified in <tt>:link_field</tt> of the linked to object (or the specified field name if it's a
+  #   self-link)
+  # * The value of the first field that the target responds to:
+  #   * <tt>name</tt>
+  #   * <tt>title</tt>
+  #   * <tt>label</tt>
+  # * The linked to object turned to a string (e.g. <tt>to_s</tt>)
+  #
+  # As you can see, in most cases you might not need to specify the text at all, but everything will be handled
+  # for you.
+  #
+  # === Custom path
+  # You might want to be able to link to a custom path, for example in the case of nested resources. You can specify
+  # a custom path via the <tt>:link_path</tt>.
+  #
+  #   field_value(@customer, :user, :link_path => customer_user_path(@customer, @customer.user))
+  #   # => "<a href=\"customers/10/users/23\">John Doe</a>"
+  #
+  # The method above have a large disadvantage, though. If +@customer.user+ is <tt>nil</tt>, you will get an excaption while
+  # generating the URL with <tt>customer_user_path</tt>. You can avoid this by specifying a lambda as the path:
+  #
+  #   field_value(@customer, :user, :link_path => lambda { customer_user_path(@customer, @customer.user) })
+  #   # => "<a href=\"customers/10/users/23\">John Doe</a>"
+  #
+  # As an added bonus, you could also get the target into the block via the first argument. Here is a full example:
+  #
+  #   field_value(@customer, :user, :link_path => lambda { |c| customer_user_path(c, c.user) })
+  #   # => "<a href=\"customers/10/users/23\">John Doe</a>"
+  #
+  #   field_value(@customer, :user,
+  #       :link_text  => "Search Google for this user's name",
+  #       :link_path  => lambda { |cust| "http://www.google.com/search?q=#{cust.full_name}" })
+  #   # => "<a href=\"http://www.google.com/search?q=Kevin Bacon\">Search Google for this user's name</a>"
+  #
+  # === Additional options
+  # Any extra options to the link_to method (like class attributes) can be passed to <tt>:link_options</tt>. They will be
+  # forwarded correctly.
+  #
+  # == Custom format
+  # You can do your own small custom formatting on top of all this by passing the <tt>:format</tt> option. The
+  # first instance of "%s" will be replaced by the value. Say that you want to display a normal number
+  # as a percent by appending a % to the end of it, just pass
+  #   :format => "%s%%"
+  # The double percent sign is to quote it from substitution.
+  #
+  #
+  # == Example
+  #   field_value(@user, :name)                       # => "John"
+  #   field_value(@user, :name, :format => "Mr. %s")  # => "Mr. John"
+  #   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"
+  #
+  def field_value(record, field, options = {})
+    FieldHelpers::Base.new(self, record, field, options).value_for_view
+  end
+  
+end

data/lib/field_helpers/kinds.rb

@@ -0,0 +1,255 @@
+# 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.
+# 
+
+# This class handles the auto-discovery and formatting of the built-in kinds.
+# It will be loaded and registered by FieldHelpers module.
+#
+# == Kind discovery
+# Kind discovery works around two things: Field name and field value.
+#
+# The field name is pretty straightforward; it's stuff like "name", "created_at"
+# and similar names. Value is also pretty easy since it's just the raw value for
+# the specified field name, which could be instances of other classes, <tt>nil</tt>, etc.
+#
+# A method that takes care of discovering types is called "discoverer". If a method
+# returns <tt>true</tt> (explicit!) the discovery will be concluded positive and the kind
+# be assumed from there. No more discoverers will be called.
+#
+# Here is an example discovery method:
+#   def discover_dog(field, value)
+#     true if value =~ /dog/i or field == :pet
+#   end
+#
+# == Kind conversion
+# Before being returned, the *value* (not default value) will always be converted to
+# the proper kind. This involves calling a "helper method" as they are called. A helper
+# method should take one argument: An instance of the "base" (FieldHelpers::Base).
+#
+# You most probably want to get a hold of the actual value in question, which you can
+# do by calling <tt>original_value</tt> on the base. Avoid calling <tt>value</tt> since you might
+# end up in an infinite loop in which <tt>value</tt> will call your helper and your helper will
+# call <tt>value</tt> again.
+#
+# If you want to access any options given to the field helpers, you can do so through
+# the base object. You can actually access about anything, even call discoverers and
+# other helpers if you so wish.
+#
+# A conversion helper should always return a string, else the behavior is undefined.
+#
+# Here is a couple of example helper methods:
+#
+#   def convert_title(base)
+#     base.original_value.to_s.titleize
+#   end
+#
+#   def convert_password(base)
+#      if base.options[:password_full]
+#        base.original_value.gsub(/./, '*')
+#      else
+#        "************"
+#      end
+#   end
+#
+class FieldHelpers::Kinds
+  class << self
+
+    # Returns a hash of <tt>kind</tt> => <tt>method proc</tt> for every kind with a helper
+    # method. This is done through metaprogamming so you only need to add methods
+    # here if you want to add new methods to the FieldHelpers core.
+    def available_kinds_with_helpers
+      flat = self.methods.collect do |m|
+        if m.to_s =~ /convert_to_(.*)/
+          [$1.to_sym, self.method(m.to_sym)]
+        else
+          nil
+        end
+      end
+      
+      Hash[*flat.compact.flatten]
+    end
+    
+    # Returns a hash of <tt>kind</tt> => <tt>method proc</tt> for every kind with a
+    # discoverer. This is done through metaprogamming so you only need to add methods
+    # here if you want to add new methods to the FieldHelpers core.
+    def available_kinds_with_discoverers
+      flat = self.methods.collect do |m|
+        if m.to_s =~ /discover_(.*)/
+          [$1.to_sym, self.method(m.to_sym)]
+        else
+          nil
+        end
+      end
+      
+      Hash[*flat.compact.flatten]
+    end
+    
+    #### Discovery methods
+    
+    # Discovers dates by looking at the following:
+    # * Field name ends with "_on"
+    # * Value is a <tt>Date</tt> instance
+    # If any of these are true, the discovery will be positive.
+    def discover_date(name, value)
+      true if name =~ /_on$/ or value.is_a?(Date)
+    end
+    
+    # Discovers datetimes by looking at the following:
+    # * Field name ends with "_at"
+    # * Value is a <tt>DateTime</tt> instance
+    # * Value is a <tt>Time</tt> instance
+    # * Value is a <tt>TimeWithZone</tt> instance
+    # If any of these are true, the discovery will be positive.
+    def discover_datetime(name, value)
+      true if name =~ /_at$/ or value.is_a?(DateTime) or value.is_a?(Time) or value.is_a?(::ActiveSupport::TimeWithZone)
+    end
+    
+    # Discovers booleans by looking at the following:
+    # * Field name ends with "?"
+    # * Value is <tt>true</tt>
+    # * Value is <tt>false</tt>
+    # If any of these are true, the discovery will be positive.
+    def discover_bool(name, value)
+      true if name =~ /\?$/ or value === true or value === false
+    end
+    
+    # Discovers money by looking at the following:
+    # * Field name contains "cost"
+    # * Field name contains "price"
+    # If any of these are true, the discovery will be positive.
+    def discover_money(name, value)
+      true if name =~ /cost|price/
+    end
+    
+    # Discovers email by looking at the following:
+    # * Field name contains "email"
+    # * Field name contains "e-mail"
+    # * Field name contains "e_mail"
+    # If any of these are true, the discovery will be positive.
+    def discover_email(name, value)
+      true if name =~ /e[-_]?mail/
+    end
+    
+    # Discovers links by looking at value and seeing if it is an <tt>ActiveRecord::Base</tt>
+    # instance
+    def discover_link(name, value)
+      true if value.kind_of?(::ActiveRecord::Base)
+    end
+    
+    ### Conversion methods
+    
+    # Just calls to_s on the value
+    def convert_to_string(base)
+      base.original_value.to_s
+    end
+    
+    # Converts to a <tt>Date</tt> instace by calling <tt>to_date</tt> and then calls <tt>to_s</tt> on it
+    def convert_to_date(base)
+      base.original_value.to_date.to_s
+    end
+    
+    # Converts to a <tt>Time</tt> instance through <tt>to_time</tt> and then calls <tt>to_s</tt> with the
+    # <tt>:time</tt> formatting.
+    # This converts full <tt>Time</tt> objects like "2009-02-06 12:34:55 +0100" into just "12:34:55"
+    def convert_to_time(base)
+      base.original_value.to_time.to_s(:time)
+    end
+    
+    # Converts to <tt>Time</tt> with <tt>to_time</tt> and then calls <tt>to_s</tt>. This will display dates
+    # in their full form.
+    def convert_to_datetime(base)
+      base.original_value.to_time.to_s
+    end
+    
+    # If value evaluates to true, returns a translation of "yes" from <tt>I18n</tt>. Else, will return
+    # a translation of "no".
+    def convert_to_bool(base)
+      return I18n.translate(:yes) if base.original_value
+      I18n.translate(:no)
+    end
+    
+    # Passes the value through <tt>number_to_currency</tt>.
+    def convert_to_money(base)
+      base.template.number_to_currency(base.original_value)
+    end
+    
+    # Passes the value through <tt>mail_to</tt>.
+    def convert_to_email(base)
+      base.template.mail_to(base.original_value)
+    end
+    
+    # This is a complex one. Please see FieldHelpers::Base for information about how this works. It is written
+    # in the class documentation.
+    #
+    # In summary: Passes the value through <tt>link_to</tt> if the value is a model instance, else passes the
+    # <tt>record</tt> through <tt>link_to</tt> with the value of the field as the text for the link. Accepts
+    # a few options, too.
+    def convert_to_link(base)
+      if base.original_value.kind_of? ActiveRecord::Base
+        target = base.original_value # Not a self-link
+      else
+        target = base.record # Self-link
+        base.options[:link_field] = base.field
+      end
+      
+      text = get_link_text(target, base)
+      path = get_link_path(target, base)
+      
+      base.template.link_to(text, path, base.options[:link_options])
+    end
+    
+    # Handles the link text logic for <tt>convert_to_link</tt>. This is an internal method but public
+    # in case you want to use it for your own helpers.
+    # 
+    # It takes the target record and then the base in which the options are stored.
+    def get_link_text(target, base)
+      options = base.options
+      if options[:link_text]
+        return options[:link_text]
+      elsif options[:link_field]
+        return target.send(options[:link_field])
+      end
+      
+      %w{name title label}.each do |field|
+        return target.send(field.to_sym) if target.respond_to?(field.to_sym)
+      end
+      
+      target.to_s
+    end
+    
+    # Handles the link path logic for <tt>convert_to_link</tt>. This is an internal method but public
+    # in case you want to use it for yout own helpers.
+    # 
+    # It takes the target record and then the base in which the options are stored.
+    def get_link_path(target, base)
+      path = base.options[:link_path]
+      if path.kind_of? Proc
+        path = path.call(target)
+      elsif path.nil?
+        path = target
+      end
+      path
+    end
+    
+  end
+  
+end