forme 0.5.0

data/lib/forme/sinatra.rb

@@ -0,0 +1,89 @@
+require 'forme'
+
+module Forme
+  module Sinatra # :nodoc:
+    # Subclass used when using Forme/Sinatra ERB integration.
+    # Handles integrating into the view template so that
+    # methods with blocks can inject strings into the output.
+    class Form < ::Forme::Form
+      # Template output object, where serialized output gets
+      # injected.
+      attr_reader :output
+
+      # Set the template output object when initializing.
+      def initialize(*)
+        super
+        @output = @opts[:output]
+      end
+
+      # Serialize the tag and inject it into the output.
+      def emit(tag)
+        output << tag.to_s
+      end
+
+      # Always return nil, so that use with <%= doesn't cause
+      # multiple things to be output. 
+      def inputs(*a)
+        super
+        nil
+      end
+
+      # Always return nil, so that use with <%= doesn't cause
+      # multiple things to be output. 
+      def form(*a, &block)
+        super
+        nil
+      end
+
+      # If a block is provided, inject an opening tag into the
+      # output, inject any given children into the output, yield to the
+      # block, inject a closing tag into the output, and the return nil
+      # so that usage with <%= doesn't cause multiple things to be output.
+      # If a block is not given, just return the tag created.
+      def tag(type, attr={}, children=[])
+        tag = _tag(type, attr, children)
+        if block_given?
+          emit(serializer.serialize_open(tag)) if serializer.respond_to?(:serialize_open)
+          children.each{|c| emit(c)}
+          yield self
+          emit(serializer.serialize_close(tag)) if serializer.respond_to?(:serialize_close)
+          nil
+        else
+          tag
+        end
+      end
+    end
+    
+    # This is the module used to add the Forme integration
+    # to Sinatra.  It should be enabled in Sinatra with the
+    # following code in your <tt>Sinatra::Base</tt> subclass:
+    #
+    #   helpers Forme::Sinatra::ERB
+    module ERB
+      # Create a +Form+ object and yield it to the block,
+      # injecting the opening form tag before yielding and
+      # the closing form tag after yielding.
+      #
+      # Argument Handling:
+      # No args :: Creates a +Form+ object with no options and not associated
+      #            to an +obj+, and with no attributes in the opening tag.
+      # 1 hash arg :: Treated as opening form tag attributes, creating a
+      #               +Form+ object with no options.
+      # 1 non-hash arg :: Treated as the +Form+'s +obj+, with empty options
+      #                   and no attributes in the opening tag.
+      # 2 hash args :: First hash is opening attributes, second hash is +Form+
+      #                options.
+      # 1 non-hash arg, 1-2 hash args :: First argument is +Form+'s obj, second is
+      #                                  opening attributes, third if provided is
+      #                                  +Form+'s options.
+      def form(obj=nil, attr={}, opts={}, &block)
+        h = {:output=>@_out_buf}
+        (obj.is_a?(Hash) ? attr = attr.merge(h) : opts = opts.merge(h))
+        Form.form(obj, attr, opts, &block)
+      end
+    end 
+
+    # Alias of <tt>Forme::Sinatra::ERB</tt>
+    Erubis = ERB
+  end
+end

data/lib/forme/version.rb

@@ -0,0 +1,9 @@
+module Forme
+  # Version constant, use <tt>Forme.version</tt> instead.
+  VERSION = '0.5.0'.freeze
+
+  # Returns the version as a frozen string (e.g. '0.1.0')
+  def self.version
+    VERSION
+  end
+end

data/lib/sequel/plugins/forme.rb

@@ -0,0 +1,435 @@
+require 'forme'
+
+module Sequel # :nodoc:
+  module Plugins # :nodoc:
+    # This Sequel plugin allows easy use of Forme with Sequel.
+    module Forme
+      # Exception class raised by the plugin.  It's important to
+      # note this descends from <tt>Forme::Error</tt> and not
+      # <tt>Sequel::Error</tt>, though in practice it's unlikely
+      # you will want to rescue these errors.
+      class Error < ::Forme::Error
+      end
+
+      # This module extends all <tt>Forme::Form</tt> instances
+      # that use a <tt>Sequel::Model</tt> instance as the form's
+      # +obj+.
+      module SequelForm
+        # Stack of objects used by subform.  The current +obj+
+        # is added to the top of the stack on a call to +subform+,
+        # the nested associated object is set as the current +obj+ during the
+        # call to +subform+, and when +subform+ returns, the top of the
+        # stack is set as the current +obj+.
+        attr_accessor :nested_associations
+
+        # The namespaces that should be added to the id and name
+        # attributes for the receiver's inputs.  Used as a stack
+        # by +subform+.
+        attr_accessor :namespaces
+
+        # Use the post method by default for Sequel forms, unless
+        # overridden with the :method attribute.
+        def form(attr={}, &block)
+          attr = {:method=>:post}.merge(attr)
+          attr[:class] = ::Forme.merge_classes(attr[:class], "forme", obj.model.send(:underscore, obj.model.name))
+          super(attr, &block)
+        end
+
+        # Call humanize on a string version of the argument if
+        # String#humanize exists. Otherwise, do some monkeying
+        # with the string manually.
+        def humanize(s)
+          s = s.to_s
+          s.respond_to?(:humanize) ? s.humanize : s.gsub(/_id$/, "").gsub(/_/, " ").capitalize
+        end
+
+        # Handle nested association usage.  The +association+ should be a name
+        # of the association for the form's +obj+. Inside the block, calls to
+        # the +input+ and +inputs+ methods for the receiver treat the associated
+        # object as the recevier's +obj+, using name and id attributes that work
+        # with the Sequel +nested_attributes+ plugin.
+        #
+        # The following options are currently supported:
+        # :inputs :: Automatically call +inputs+ with the given values.  Using
+        #            this, it is not required to pass a block to the method,
+        #            though it will still work if you do.
+        # :legend :: If :inputs is also used, this is passed to it to override
+        #            the default :legend used.  You can also use a proc as the value,
+        #            which will called with each associated object (and the position
+        #            in the associated object already for *_to_many associations),
+        #            and should return the legend string to use for that object.
+        def subform(association, opts={}, &block)
+          nested_obj = opts.has_key?(:obj) ? opts[:obj] : obj.send(association)
+          ref = obj.class.association_reflection(association)
+          multiple = ref.returns_array?
+          i = -1
+          ins = opts[:inputs]
+          Array(nested_obj).each do |no|
+            begin
+              nested_associations << obj
+              namespaces << "#{association}_attributes"
+              namespaces << (i+=1) if multiple
+              @obj = no
+              emit(input(ref.associated_class.primary_key, :type=>:hidden, :label=>nil)) unless no.new?
+              if ins
+                options = opts.dup
+                if options.has_key?(:legend)
+                  if options[:legend].respond_to?(:call)
+                    options[:legend] = multiple ? options[:legend].call(no, i) : options[:legend].call(no)
+                  end
+                else
+                  if multiple
+                    options[:legend] = humanize("#{obj.model.send(:singularize, association)} ##{i+1}")
+                  else
+                    options[:legend] = humanize(association)
+                  end
+                end
+                inputs(ins, options, &block)  
+              else
+                yield
+              end
+            ensure
+              @obj = nested_associations.pop
+              namespaces.pop if multiple
+              namespaces.pop
+            end
+          end
+          nil
+        end
+
+        # Return a unique id attribute for the +field+, handling
+        # nested attributes use.
+        def namespaced_id(field)
+          "#{namespaces.join('_')}_#{field}"
+        end
+
+        # Return a unique name attribute for the +field+, handling nested
+        # attribute use.  If +multiple+ is true, end the name
+        # with [] so that param parsing will treat the name as part of an array.
+        def namespaced_name(field, multiple=false)
+          root, *nsps = namespaces
+          "#{root}#{nsps.map{|n| "[#{n}]"}.join}[#{field}]#{'[]' if multiple}"
+        end
+      end
+
+      # Helper class for dealing with Forme/Sequel integration.
+      # One instance is created for each call to <tt>Forme::Form#input</tt>
+      # for forms associated with <tt>Sequel::Model</tt> objects.
+      class SequelInput
+        include ::Forme
+
+        # The name methods that will be tried, in order, to get the
+        # text to use for the options in the select input created
+        # for associations.
+        FORME_NAME_METHODS = [:forme_name, :name, :title, :number]
+
+        # The <tt>Sequel::Model</tt> object related to the receiver.
+        attr_reader :obj
+
+        # The form related to the receiver.
+        attr_reader :form
+
+        # The field/column name related to the receiver.  The type of
+        # input created usually depends upon this field.
+        attr_reader :field
+
+        # The options hash related to the receiver.
+        attr_reader :opts
+
+        # Set the +obj+, +form+, +field+, and +opts+ attributes.
+        def initialize(obj, form, field, opts)
+          @obj, @form, @field, @opts = obj, form, field, opts
+        end
+
+        # Determine which type of input to used based on the +field+.
+        # If the field is a column, use the column's type to determine
+        # an appropriate field type. If the field is an association,
+        # use either a regular or multiple select input (or multiple radios or
+        # checkboxes if the related :type option is used).  If it's not a
+        # column or association, but the object responds to +field+,
+        # create a text input.  Otherwise, raise an +Error+.
+        def input
+          opts[:attr] = opts[:attr] ? opts[:attr].dup : {}
+          opts[:wrapper_attr] = opts[:wrapper_attr] ? opts[:wrapper_attr].dup : {}
+
+          if sch = obj.db_schema[field] 
+            handle_errors(field)
+            handle_validations(field)
+            meth = :"input_#{sch[:type]}"
+            opts[:id] = form.namespaced_id(field) unless opts.has_key?(:id)
+            opts[:name] = form.namespaced_name(field) unless opts.has_key?(:name)
+            opts[:required] = true if !opts.has_key?(:required) && sch[:allow_null] == false && sch[:type] != :boolean
+            handle_label(field)
+
+            ::Forme.attr_classes(opts[:wrapper_attr], sch[:type])
+            ::Forme.attr_classes(opts[:wrapper_attr], "required") if opts[:required]
+
+            if respond_to?(meth, true)
+              send(meth, sch)
+            else
+              input_other(sch)
+            end
+          elsif ref = obj.model.association_reflection(field)
+            ::Forme.attr_classes(opts[:wrapper_attr], ref[:type])
+            meth = :"association_#{ref[:type]}"
+            if respond_to?(meth, true)
+              send(meth, ref)
+            else
+              raise Error, "Association type #{ref[:type]} not currently handled for association #{ref[:name]}"
+            end
+          elsif obj.respond_to?(field)
+            opts[:id] = form.namespaced_id(field) unless opts.has_key?(:id)
+            opts[:name] = form.namespaced_name(field) unless opts.has_key?(:name)
+            handle_label(field)
+            input_other({})
+          else
+            raise Error, "Unrecognized field used: #{field}"
+          end
+        end
+
+        private
+
+        # Create an +Input+ instance associated to the receiver's +form+
+        # with the given arguments.
+        def _input(*a)
+          form._input(*a)
+        end
+
+        # Set the error option correctly if the field contains errors
+        def handle_errors(f)
+          if e = obj.errors.on(f)
+            opts[:error] = e.join(', ')
+          end
+        end
+
+        # Set the label option appropriately, adding a * if the field
+        # is required.
+        def handle_label(f)
+          unless opts.has_key?(:label)
+            opts[:label] = if opts[:required]
+              [humanize(field), form._tag(:abbr, {:title=>'required'}, '*')]
+            else
+              humanize(field)
+            end
+          end
+        end
+
+        # Update the attributes and options for any recognized validations
+        def handle_validations(f)
+          m = obj.model
+          if m.respond_to?(:validation_reflections) and (vs = m.validation_reflections[f])
+            attr = opts[:attr]
+            vs.each do |type, options|
+              attr[:placeholder] = options[:placeholder] if options[:placeholder] && !attr.has_key?(:placeholder)
+
+              case type
+              when :format
+                attr[:pattern] = options[:with].source unless attr.has_key?(:pattern)
+                attr[:title] = options[:title] unless attr.has_key?(:title)
+              when :length
+                unless attr.has_key?(:maxlength)
+                  if max =(options[:maximum] || options[:is])
+                    attr[:maxlength] = max
+                  elsif (w = options[:within]) && w.is_a?(Range)
+                    attr[:maxlength] = if w.exclude_end? && w.end.is_a?(Integer)
+                      w.end - 1
+                    else
+                      w.end
+                    end
+                  end
+                end
+              when :numericality
+                unless attr.has_key?(:pattern)
+                  attr[:pattern] = if options[:only_integer]
+                    "^[+\\-]?\\d+$"
+                  else
+                    "^[+\\-]?\\d+(\\.\\d+)?$"
+                  end
+                end
+                attr[:title] = options[:title] || "must be a number" unless attr.has_key?(:title)
+              end
+            end
+          end
+        end
+
+        # If the :name_method option is provided, use that as the method.
+        # Otherwise, pick the first method in +FORME_NAME_METHODS+ that
+        # the associated class implements and use it.  If none of the
+        # methods are implemented by the associated class, raise an +Error+.
+        def forme_name_method(ref)
+          if meth = opts.delete(:name_method)
+            meth
+          else
+            meths = FORME_NAME_METHODS & ref.associated_class.instance_methods.map{|s| s.to_sym}
+            if meths.empty?
+              raise Error, "No suitable name method found for association #{ref[:name]}"
+            else
+              meths.first
+            end
+          end
+        end
+
+        # Create a select input made up of options for all entries the object
+        # could be associated to, with the one currently associated to being selected.
+        # If the :type=>:radio option is used, use multiple radio buttons instead of
+        # a select box.  For :type=>:radio, you can also provide a :tag_wrapper option
+        # used to wrap the individual radio buttons.
+        def association_many_to_one(ref)
+          key = ref[:key]
+          handle_errors(key)
+          opts[:name] = form.namespaced_name(key) unless opts.has_key?(:name)
+          opts[:value] = obj.send(key) unless opts.has_key?(:value)
+          opts[:options] = association_select_options(ref) unless opts.has_key?(:options)
+          if opts.delete(:as) == :radio
+            handle_label(field)
+            label = opts.delete(:label)
+            val = opts.delete(:value)
+            tag_wrapper = opts.delete(:tag_wrapper) || :default
+            wrapper = form.transformer(:wrapper, opts)
+            opts.delete(:wrapper)
+            radios = opts.delete(:options).map{|l, pk| _input(:radio, opts.merge(:value=>pk, :wrapper=>tag_wrapper, :label=>l, :checked=>(pk == val)))}
+            radios.unshift("#{label}: ")
+            wrapper ? wrapper.call(radios, _input(:radio, opts)) : radios
+          else
+            opts[:id] = form.namespaced_id(key) unless opts.has_key?(:id)
+            opts[:add_blank] = true if !opts.has_key?(:add_blank)
+            opts[:required] = true if !opts.has_key?(:required) && (sch = obj.model.db_schema[key]) && !sch[:allow_null]
+            handle_label(field)
+            ::Forme.attr_classes(opts[:wrapper_attr], "required") if opts[:required]
+            _input(:select, opts)
+          end
+        end
+
+        # Create a multiple select input made up of options for all entries the object
+        # could be associated to, with all of the ones currently associated to being selected.
+        # If the :type=>:checkbox option is used, use multiple checkboxes instead of
+        # a multiple select box.  For :type=>:checkbox, you can also provide a :tag_wrapper option
+        # used to wrap the individual checkboxes.
+        def association_one_to_many(ref)
+          key = ref[:key]
+          klass = ref.associated_class
+          pk = klass.primary_key
+          field = "#{klass.send(:singularize, ref[:name])}_pks"
+          opts[:name] = form.namespaced_name(field, :multiple) unless opts.has_key?(:name)
+          opts[:value] = obj.send(ref[:name]).map{|x| x.send(pk)} unless opts.has_key?(:value)
+          opts[:options] = association_select_options(ref) unless opts.has_key?(:options)
+          handle_label(field)
+          if opts.delete(:as) == :checkbox
+            label = opts.delete(:label)
+            val = opts.delete(:value)
+            tag_wrapper = opts.delete(:tag_wrapper) || :default
+            wrapper = form.transformer(:wrapper, opts)
+            opts.delete(:wrapper)
+            cbs = opts.delete(:options).map{|l, pk| _input(:checkbox, opts.merge(:value=>pk, :wrapper=>tag_wrapper, :label=>l, :checked=>val.include?(pk), :no_hidden=>true))}
+            cbs.unshift("#{label}: ")
+            wrapper ? wrapper.call(cbs, _input(:checkbox, opts)) : cbs
+          else
+            opts[:id] = form.namespaced_id(field) unless opts.has_key?(:id)
+            opts[:multiple] = true
+            _input(:select, opts)
+          end
+        end
+        alias association_many_to_many association_one_to_many
+
+        # Return an array of two element arrays representing the
+        # select options that should be created.
+        def association_select_options(ref)
+          name_method = forme_name_method(ref)
+          obj.send(:_apply_association_options, ref, ref.associated_class.dataset).unlimited.all.map{|a| [a.send(name_method), a.pk]}
+        end
+
+        # Delegate to the +form+.
+        def humanize(s)
+          form.humanize(s)
+        end
+
+        # If the column allows +NULL+ values, use a three-valued select
+        # input.  If not, use a simple checkbox.
+        def input_boolean(sch)
+          if sch[:allow_null]
+            v = opts[:value] || obj.send(field)
+            opts[:value] = (v ? 't' : 'f') unless v.nil?
+            opts[:add_blank] = true
+            opts[:options] = [['True', 't'], ['False', 'f']]
+            _input(:select, opts)
+          else
+            opts[:checked] = obj.send(field)
+            opts[:value] = 't'
+            _input(:checkbox, opts)
+          end
+        end
+
+        # Use a file type for blobs.
+        def input_blob(sch)
+          opts[:value] = nil
+          standard_input(:file)
+        end
+
+        # Use the text type by default for other cases not handled.
+        def input_string(sch)
+          if opts[:as] == :textarea
+            standard_input(:textarea)
+          else
+            case field.to_s
+            when "password"
+              opts[:value] = nil
+              standard_input(:password)
+            when "email"
+              standard_input(:email)
+            when "phone", "fax"
+              standard_input(:tel)
+            when "url", "uri", "website"
+              standard_input(:url)
+            else
+              standard_input(:text)
+            end
+          end
+        end
+
+        # Use number inputs for integers.
+        def input_integer(sch)
+          standard_input(:number)
+        end
+
+        # Use date inputs for dates.
+        def input_date(sch)
+          standard_input(:date)
+        end
+
+        # Use datetime inputs for datetimes.
+        def input_datetime(sch)
+          standard_input(:datetime)
+        end
+
+        # Use a text input for all other types.
+        def input_other(sch)
+          standard_input(:text)
+        end
+
+        # Allow overriding the given type using the :type option,
+        # and set the :value option to the field value unless it
+        # is overridden.
+        def standard_input(type)
+          type = opts.delete(:type) || type
+          opts[:value] = obj.send(field) unless opts.has_key?(:value)
+          _input(type, opts)
+        end
+      end
+
+      module InstanceMethods
+        # Configure the +form+ with support for <tt>Sequel::Model</tt>
+        # specific code, such as support for nested attributes.
+        def forme_config(form)
+          form.extend(SequelForm)
+          form.nested_associations = []
+          form.namespaces = [model.send(:underscore, model.name)]
+        end
+
+        # Return <tt>Forme::Input</tt> instance based on the given arguments.
+        def forme_input(form, field, opts)
+          SequelInput.new(self, form, field, opts).input
+        end
+      end
+    end
+  end
+end