presenting 1.0.0

data/lib/presentation/form.rb

@@ -0,0 +1,149 @@
+module Presentation
+  class Form < Base
+    # TODO
+    # field type              extra details?
+    # * text
+    # * text_area
+    # * password
+    # * check_box             checked/unchecked values
+    # * radio (= dropdown)    options
+    # * dropdown (= radio)    options
+    # * multi-select          options
+    # * recordselect          url?
+    # * calendar              constraints
+    # * time                  constraints
+    # * date
+    # * datetime
+    #
+    # other
+    # - example / description / help text
+    # - nested fields
+    
+    # Fields may be grouped. Groups may or may not have names. Here's how:
+    #
+    #   Presentation::Form.new(:groups => [
+    #     [:a, :b],             # creates a nameless group with fields :a and :b
+    #     {"foo" => [:c, :d]}   # creates a group named "foo" with fields :c and :d
+    #   ])
+    #
+    # Note that if you don't need groups it'll be simpler to just use fields= instead.
+    def groups
+      @groups ||= GroupSet.new
+    end
+    def groups=(args)
+      args.each do |group|
+        groups << group
+      end
+    end
+
+    class GroupSet < Array
+      def <<(val)
+        if val.is_a? Hash
+          opts = {:name => val.keys.first, :fields => val.values.first}
+        else
+          opts = {:fields => val}
+        end
+        super Group.new(opts)
+      end
+    end
+    
+    class Group
+      include Presenting::Configurable
+      
+      # a completely optional group name
+      attr_accessor :name
+      
+      # the fields in the group
+      def fields
+        @fields ||= Presenting::FieldSet.new(Field, :name, :type)
+      end
+      def fields=(args)
+        args.each do |field|
+          fields << field
+        end
+      end
+    end
+
+    # Used to define fields in a group-less form.
+    def fields
+      if groups.empty?
+        groups << []
+      end
+      groups.first.fields
+    end
+    def fields=(args)
+      args.each do |field|
+        fields << field
+      end
+    end
+    
+    # The url where the form posts. May be anything that url_for accepts, including
+    # a set of records.
+    def url
+      @url ||= presentable
+    end
+    attr_writer :url
+    
+    # What method the form should use to post. Should default intelligently enough from
+    # the presentable. Not sure what use case would require it being set manually.
+    def method
+      @method ||= presentable.new_record? ? :post : :put
+    end
+    attr_writer :method
+
+    # the text on the submit button
+    def button
+      @button ||= presentable.new_record? ? 'Create' : 'Update'
+    end
+    attr_writer :button
+    
+    # a passthrough for form_for's html. useful for classifying a form for ajax behavior (e.g. :html => {:class => 'ajax'})
+    attr_accessor :html
+
+    class Field
+      include Presenting::Configurable
+      
+      # the display label of the field
+      def label
+        @label ||= name.to_s.titleize
+      end
+      attr_writer :label
+      
+      # the parameter name of the field
+      attr_accessor :name
+
+      # where the value for this field comes from.
+      # - String: a fixed value
+      # - Symbol: a method on the record (no arguments)
+      # - Proc: a custom block that accepts the record as an argument
+      def value
+        @value ||= name.to_sym
+      end
+      attr_writer :value
+      
+      def value_from(obj) #:nodoc:
+        v = case value
+          when Symbol: obj.send(value)
+          when String: value
+          when Proc:   value.call(obj)
+        end
+      end
+      
+      # the widget type for the field. use type_options to pass arguments to the widget.
+      def type
+        @type ||= :string
+      end
+      attr_writer :type
+      
+      # unrestricted options storage for the widget type. this could be a list of options for a select, or extra configuration for a calendar widget.
+      attr_accessor :type_options
+    end
+
+    def iname; :form end
+
+    delegate :request_forgery_protection_token, :allow_forgery_protection, :to => :controller
+    def protect_against_forgery? #:nodoc:
+      allow_forgery_protection && request_forgery_protection_token
+    end
+  end
+end

data/lib/presentation/grid.rb

@@ -0,0 +1,160 @@
+module Presentation
+  # TODO: ability to render a hash
+  # TODO: custom css classes for rows and/or cells
+  # TODO: document or complain for required options -- id and fields
+  # TODO: make fields= accept an ActiveRecord::Base.columns array for a default field set
+  class Grid < Base
+    # The id for this presentation. Required.
+    attr_accessor :id
+    
+    # The display title for this presentation. Will default based on the id.
+    attr_writer :title
+    def title
+      @title ||= self.id.titleize
+    end
+    
+    # Paradigm Example:
+    #   Grid.new(:fields => [
+    #     :email,
+    #     {"Full Name" => proc{|r| [r.first_name, r.last_name].join(' ')}},
+    #     {"Roles" => {:value => :roles, :type => :collection}}
+    #   ])
+    #
+    # Is equivalent to:
+    #   g = Grid.new
+    #   g.fields << :email
+    #   g.fields << {"Full Name" => proc{|r| [r.first_name, r.last_name].join(' ')},
+    #   g.fields << {"Roles" => {:value => :roles, :type => :collection}}
+    def fields=(args)
+      args.each do |field|
+        self.fields << field
+      end
+    end
+    
+    def fields
+      @fields ||= Presenting::FieldSet.new(Field, :name, :value)
+    end
+    
+    def colspan
+      @colspan ||= fields.size + (record_links.empty? ? 0 : 1)
+    end
+    
+    def iname; :grid end
+
+    class Field < Presenting::Attribute
+      # Defines how this field sorts. This means two things:
+      #   1. whether it sorts
+      #   2. what name it uses to sort
+      #
+      # Examples:
+      #
+      #   # The field is sortable and assumes the sort_name of "first_name".
+      #   # This is the default.
+      #   Field.new(:sortable => true, :name => "First Name")
+      #
+      #   # The field is sortable and assumes the sort_name of "first".
+      #   Field.new(:sortable => 'first', :name => 'First Name')
+      #
+      #   # The field is unsortable.
+      #   Field.new(:sortable => false)
+      def sortable=(val)
+        @sort_name = case val
+          when TrueClass:             self.id
+          when FalseClass, NilClass:  nil          
+          else                        val.to_s
+        end
+      end
+      
+      # if the field is sortable at all
+      def sortable?
+        self.sortable = Presenting::Defaults.grid_is_sortable unless defined? @sort_name
+        !@sort_name.blank?
+      end
+      
+      attr_reader :sort_name
+      
+      # is this field sorted in the given request?
+      def is_sorted?(request)
+        @is_sorted ||= if sortable? and sorting = request.query_parameters["sort"] and sorting[sort_name]
+          sorting[sort_name].to_s.match(/desc/i) ? 'desc' : 'asc'
+        else
+          false
+        end
+      end
+      
+      # for the view -- modifies the current request such that it would sort this field.
+      def sorted_url(request)
+        if current_direction = is_sorted?(request)
+          next_direction = current_direction == 'desc' ? 'asc' : 'desc'
+        else
+          next_direction = 'desc'
+        end
+        request.path + '?' + request.query_parameters.merge("sort" => {sort_name => next_direction}).to_param
+      end
+      
+      ##
+      ## Planned
+      ##
+
+      # TODO: discover "type" from data class (ActiveRecord) if available
+      # TODO: decorate a Hash object so type is specifiable there as well
+      # PLAN: type should determine how a field renders. custom types for custom renders. this should be the second option to present().
+      # attr_accessor :type
+      
+      # PLAN: a field's description would appear in the header column, perhaps only visibly in a tooltip
+      # attr_accessor :description
+      
+      # PLAN: any field may be linked. this would happen after :value and :type.
+      # attr_accessor :link
+    end
+
+    # Links are an area where I almost made the mistake of too much configuration. Presentations are configured in the view,
+    # and all of the view helpers are available. When I looked at the (simple) configuration I was building and realized that
+    # I could just as easily take the result of link_to, well, I felt a little silly.
+    #
+    # Compare:
+    #
+    #   @grid.links = [
+    #     {:name => 'Foo', :url => foo_path, :class => 'foo'}
+    #   ]
+    #
+    # vs:
+    #
+    #   @grid.links = [
+    #     link_to('Foo', foo_path, :class => 'foo')
+    #   ]
+    #
+    # Not only is the second example (the supported example, by the way) shorter and cleaner, it encourages the developer
+    # to stay in touch with the Rails internals and therefore discourages a configuration-heavy mindset.
+    def links=(set)
+      set.compact.each do |link|
+        raise ArgumentError, "Links must be strings, such as the output of link_to()." unless link.is_a?(String)
+        links << link
+      end
+    end
+    def links
+      @links ||= []
+    end
+    
+    # Like links, except the link will appear for each record. This means that the link must be a block that accepts the
+    # record as its argument. For example:
+    #
+    # @grid.record_links = [
+    #   proc{|record| link_to("Foo", foo_path(record), :class => 'foo') }
+    # ]
+    #
+    def record_links=(set)
+      set.compact.each do |link|
+        raise ArgumentError, "Record links must be blocks that accept the record as an argument." unless link.respond_to?(:call) and link.arity == 1
+        record_links << link
+      end
+    end
+    def record_links
+      @record_links ||= []
+    end
+    
+    def paginate?
+      defined? WillPaginate and presentable.is_a?(WillPaginate::Collection)
+    end
+  end
+end

data/lib/presentation/search.rb

@@ -0,0 +1,9 @@
+module Presentation
+  class Search < Base
+    def iname; :search end
+    
+    def url
+      request.path + '?' + request.query_parameters.except("search").to_param
+    end
+  end
+end

data/lib/presenting/attribute.rb

@@ -0,0 +1,51 @@
+module Presenting
+  # represents an attribute meant to be read from a record
+  # used for things like Grid and Details.
+  # not intended for things like Form or FieldSearch
+  class Attribute
+    include Presenting::Configurable
+    
+    def name=(val)
+      self.value ||= val # don't lazy define :value, because we're about to typecast here
+      if val.is_a? Symbol
+        @name = val.to_s.titleize
+      else
+        @name = val.to_s
+      end
+    end
+    attr_reader :name
+    
+    # The short programmatic name for this field. Can be used as a CSS class, sorting name, etc.
+    def id=(val)
+      @id = val.to_s
+    end
+    
+    def id
+      @id ||= name.to_s.underscore.gsub(/[^a-z0-9]/i, '_').gsub(/__+/, '_').sub(/_$/, '')
+    end
+  
+    # Where a field's value comes from. Depends heavily on the data type you provide.
+    # - String: fixed value (as provided)
+    # - Symbol: a method on the record (no arguments)
+    # - Proc: a custom block that accepts the record as an argument
+    attr_accessor :value
+    
+    def value_from(obj) #:nodoc:
+      case value
+        when Symbol: obj.is_a?(Hash) ? obj[value] : obj.send(value)
+        when String: value
+        when Proc:   value.call(obj)
+      end
+    end
+    
+    # whether html should be sanitize. right now this actually means html escaping.
+    # consider: by default, do not sanitize if value is a String?
+    attr_writer :sanitize
+    def sanitize?
+      unless defined? @sanitize
+        @sanitize = Presenting::Defaults.sanitize_fields
+      end
+      @sanitize
+    end
+  end
+end

data/lib/presenting/configurable.rb

@@ -0,0 +1,10 @@
+module Presenting
+  module Configurable
+    def initialize(options = {}, &block)
+      options.each do |k, v|
+        self.send("#{k}=", v)
+      end
+      yield self if block_given?
+    end
+  end
+end

data/lib/presenting/defaults.rb

@@ -0,0 +1,10 @@
+module Presenting::Defaults
+  # Whether the columns in the Grid should be sortable by default
+  mattr_accessor :grid_is_sortable
+  self.grid_is_sortable = true
+  
+  # Whether fields should be sanitized by default
+  mattr_accessor :sanitize_fields
+  self.sanitize_fields = true
+end
+

data/lib/presenting/field_set.rb

@@ -0,0 +1,26 @@
+class Presenting::FieldSet < Array
+  def initialize(field_class, primary, secondary)
+    @klass = field_class
+    @primary_attribute = primary
+    @secondary_attribute = secondary
+  end
+
+  def <<(field)
+    if field.is_a? Hash
+      k, v = *field.to_a.first
+      opts = v.is_a?(Hash) ? v : {@secondary_attribute => v}
+      opts[@primary_attribute] = k
+    else
+      opts = {@primary_attribute => field}
+    end
+    super @klass.new(opts)
+  end
+  
+  def [](key)
+    detect{|i| i.send(@primary_attribute) == key}
+  end
+  
+  def []=(key, val)
+    self << {key => val}
+  end
+end

data/lib/presenting/form_helpers.rb

@@ -0,0 +1,51 @@
+module Presenting::FormHelpers
+  def present(field)
+    send("present_#{field.type}_input", field)
+  end
+  
+  def present_readonly_input(field)
+    text_field field.name, :disabled => true, :value => field.value_from(object)
+  end
+  
+  def present_string_input(field)
+    text_field field.name, :value => field.value_from(object)
+  end
+  
+  def present_hidden_input(field)
+    hidden_field field.name, :value => field.value_from(object)
+  end
+  
+  def present_text_input(field)
+    text_area field.name, :value => field.value_from(object)
+  end
+  
+  def present_password_input(field)
+    password_field field.name
+  end
+  
+  def present_boolean_input(field)
+    check_box field.name
+  end
+  
+  def present_dropdown_input(field)
+    view.select_tag "#{object_name}[#{field.name}]", view.options_for_select(field.type_options, object.send(field.name))
+  end
+  alias_method :present_select_input, :present_dropdown_input
+  
+  def present_multi_select_input(field)
+    view.select_tag "#{object_name}[#{field.name}][]", view.options_for_select(field.type_options, object.send(field.name)), :multiple => true
+  end
+  
+  def present_radios_input(field)
+    field.type_options.collect do |(display, value)|
+      label("#{field.name}_#{value}", display) +
+      radio_button(field.name, value)
+    end.join
+  end
+  
+  private
+  
+  def view
+    @template
+  end
+end

data/lib/presenting/helpers.rb

@@ -0,0 +1,110 @@
+module Presenting
+  module Helpers
+    def presentation_stylesheets(*args)
+      stylesheet_link_tag presentation_stylesheet_path(args.sort.join(','))
+    end
+    
+    def presentation_javascript(*args)
+      javascript_include_tag presentation_javascript_path(args.sort.join(','))
+    end
+    
+    def present(*args, &block)
+      options = args.length > 1 ? args.extract_options! : {}
+      
+      if args.first.is_a? Symbol
+        object, presentation = nil, args.first
+      else
+        object, presentation = args.first, args.second
+      end
+
+      if presentation
+        klass = "Presentation::#{presentation.to_s.camelcase}".constantize rescue nil
+        if klass
+          instance = klass.new(options, &block)
+          instance.presentable = object
+          instance.controller = controller
+          instance.render
+        elsif respond_to?(method_name = "present_#{presentation}")
+          send(method_name, object, options)
+        else
+          raise ArgumentError, "unknown presentation `#{presentation}'"
+        end
+      elsif object.respond_to?(:loaded?) # AssociationProxy
+        present_association(object, options)
+      else
+        present_by_class(object, options)
+      end
+    end
+    
+    # presents a text search widget for the given field (a Presentation::FieldSearch::Field, probably)
+    def present_text_search(field, options = {})
+      current_value = (params[:search][field.param][:value] rescue nil)
+      text_field_tag options[:name], h(current_value)
+    end
+    
+    # presents a checkbox search widget for the given field (a Presentation::FieldSearch::Field, probably)
+    def present_checkbox_search(field, options = {})
+      current_value = (params[:search][field.param][:value] rescue nil)
+      check_box_tag options[:name], '1', current_value.to_s == '1'
+    end
+    
+    # presents a dropdown/select search widget for the given field (a Presentation::FieldSearch::Field, probably)
+    def present_dropdown_search(field, options = {})
+      current_value = (params[:search][field.param][:value] rescue nil)
+      select_tag options[:name], options_for_select(normalize_dropdown_options_to_strings(field.options), current_value)
+    end
+    
+    protected
+    
+    # We want to normalize the value elements of the dropdown options to strings so that
+    # they will match against params[:search].
+    #
+    # Need to handle the three different dropdown options formats:
+    # * array of strings
+    # * array of arrays
+    # * hash
+    def normalize_dropdown_options_to_strings(options)
+      options.to_a.map do |element|
+        if element.is_a? String
+          [element, element]
+        else
+          [element.first, element.last.to_s]
+        end
+      end
+    end
+
+    # TODO: special handling for associations (displaying activerecords)
+    def present_association(object, options = {})
+      present_by_class(object, options)
+    end
+    
+    def present_by_class(object, options = {})
+      case object
+        when Array
+        content_tag "ol" do
+          object.collect do |i|
+            content_tag "li", present(i, options)
+          end.join.html_safe
+        end
+        
+        when Hash
+        # sort by keys
+        content_tag "dl" do
+          object.keys.sort.collect do |k|
+            content_tag("dt", k) +
+            content_tag("dd", present(object[k], options))
+          end.join.html_safe
+        end
+        
+        when TrueClass, FalseClass
+        object ? "True" : "False"
+        
+        when Date, Time, DateTime
+        l(object, :format => :default)
+        
+        else
+        options[:h] ? h(object.to_s) : object.to_s
+      end 
+    end
+  end
+end

data/lib/presenting/sanitize.rb

@@ -0,0 +1,19 @@
+module Presenting::Sanitize
+  class << self
+    include ERB::Util
+    
+    # escape but preserve Arrays and Hashes
+    def h(val)
+      case val
+        when Array
+        val.map{|i| h(i)}
+        
+        when Hash
+        val.clone.each{|k, v| val[h(k)] = h(v)}
+        
+        else
+        html_escape(val)
+      end
+    end
+  end
+end