visionmedia-dm-forms 0.0.2

data/History.rdoc

@@ -0,0 +1,4 @@
+
+=== 0.0.1 / 2009-01-13
+
+* Initial release

data/Manifest

@@ -0,0 +1,27 @@
+History.rdoc
+Manifest
+README.rdoc
+Rakefile
+Todo.rdoc
+examples/benchmarks.rb
+examples/datamapper.rb
+examples/elements.rb
+examples/haml.rb
+examples/login.haml
+lib/dm-forms.rb
+lib/dm-forms/core_ext.rb
+lib/dm-forms/elements.rb
+lib/dm-forms/model_elements.rb
+lib/dm-forms/tag.rb
+lib/dm-forms/version.rb
+spec/functional/core_ext_spec.rb
+spec/functional/elements_spec.rb
+spec/functional/tag_spec.rb
+spec/integration/datamapper_spec.rb
+spec/integration/haml_spec.rb
+spec/spec_helper.rb
+tasks/benchmarks.rake
+tasks/docs.rake
+tasks/gemspec.rake
+tasks/spec.rake
+

data/README.rdoc

@@ -0,0 +1,62 @@
+
+= DataMapper Forms
+
+DataMapper model form generation.
+
+== Features:
+
+* Integrates with DataMapper
+* Fast; over 1000 elements in 0.1 seconds (rake benchmark)
+* Error reporting
+* Handles restful HTTP verbs
+* Provides low-level form elements uncoupled from DataMapper
+
+== Examples:
+
+Pretend in a magical world we have a User model, and only the email is valid while we are updating.
+Based on the situation above, the form would render similar to the markup beneath the
+example.
+
+   errors_for @user
+   form_for @user, :action => '/user' do |f|
+     f.textfield :name, :label => 'Name'
+     f.textfield :email, :label => 'Email'
+     f.submit :op, :value => 'Update'
+   end
+
+   <ul class="messages error">
+     <li>Name has an invalid format</li>
+   </ul>
+   <form action="/user" method="post" id="form-user">
+     <input type="hidden" name="_method" value="put" />
+     <label for="name">Name:</label>
+     <input type="textfield" class="error form-textfield form-name" name="name" />
+     <label for="email">Email:</label>
+     <input type="textfield" class="form-textfield form-email" name="email" />
+     <input type="submit" class="form-submit form-op" value="Update" name="op" />
+   </form>
+
+== License:
+
+(The MIT License)
+
+Copyright (c) 2008 TJ Holowaychuk
+
+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, an d/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.

data/Rakefile

@@ -0,0 +1,16 @@
+
+require 'rubygems'
+require 'rake'
+require 'echoe'
+require './lib/dm-forms.rb'
+
+Echoe.new("dm-forms", DataMapper::Form::VERSION::STRING) do |p|
+  p.author = "TJ Holowaychuk"
+  p.email = "tj@vision-media.ca"
+  p.summary = "DataMapper model form generation"
+  p.url = "http://github.com/visionmedia/dm-forms"
+  p.runtime_dependencies = ['dm-core']
+  p.development_dependencies = ['rspec_hpricot_matchers']
+end
+
+Dir['tasks/**/*.rake'].sort.each { |lib| load lib }

data/Todo.rdoc

@@ -0,0 +1,27 @@
+
+== Major:
+
+* match messages markup to jquery ui if reasonable
+* <optgroup label
+* assign :required based on model?
+* clean up examples
+* use have_tag matcher
+* add enctype automatically
+* Fix select option ordering ... poor unordered hashes :(
+* Add nesting to select options, and select groups
+* escape xml in attrs
+* Support both instance_eval and block
+* wrap all in div class="form-TYPE" and adjust spec...
+* XHTML ... validate 
+* perform some indenting (or all but make it optional)
+* increase performance
+* preview rdoc / finish documenting ...
+
+== Minor:
+
+* Aggregate / faux elements ...
+  * date_field :bday, :format => 'YYYY-MM-DD', :value => '1987-05-25'
+
+== Brainstorming:
+
+* Nothing

data/dm-forms.gemspec

@@ -0,0 +1,37 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{dm-forms}
+  s.version = "0.0.2"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["TJ Holowaychuk"]
+  s.date = %q{2009-01-15}
+  s.description = %q{DataMapper model form generation}
+  s.email = %q{tj@vision-media.ca}
+  s.extra_rdoc_files = ["README.rdoc", "lib/dm-forms.rb", "lib/dm-forms/core_ext.rb", "lib/dm-forms/elements.rb", "lib/dm-forms/model_elements.rb", "lib/dm-forms/tag.rb", "lib/dm-forms/version.rb", "tasks/benchmarks.rake", "tasks/docs.rake", "tasks/gemspec.rake", "tasks/spec.rake"]
+  s.files = ["History.rdoc", "Manifest", "README.rdoc", "Rakefile", "Todo.rdoc", "examples/benchmarks.rb", "examples/datamapper.rb", "examples/elements.rb", "examples/haml.rb", "examples/login.haml", "lib/dm-forms.rb", "lib/dm-forms/core_ext.rb", "lib/dm-forms/elements.rb", "lib/dm-forms/model_elements.rb", "lib/dm-forms/tag.rb", "lib/dm-forms/version.rb", "spec/functional/core_ext_spec.rb", "spec/functional/elements_spec.rb", "spec/functional/tag_spec.rb", "spec/integration/datamapper_spec.rb", "spec/integration/haml_spec.rb", "spec/spec_helper.rb", "tasks/benchmarks.rake", "tasks/docs.rake", "tasks/gemspec.rake", "tasks/spec.rake", "dm-forms.gemspec"]
+  s.has_rdoc = true
+  s.homepage = %q{http://github.com/visionmedia/dm-forms}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Dm-forms", "--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{dm-forms}
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{DataMapper model form generation}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<dm-core>, [">= 0"])
+      s.add_development_dependency(%q<rspec_hpricot_matchers>, [">= 0"])
+    else
+      s.add_dependency(%q<dm-core>, [">= 0"])
+      s.add_dependency(%q<rspec_hpricot_matchers>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<dm-core>, [">= 0"])
+    s.add_dependency(%q<rspec_hpricot_matchers>, [">= 0"])
+  end
+end

data/examples/benchmarks.rb

@@ -0,0 +1,118 @@
+
+$:.unshift File.expand_path(File.dirname(__FILE__) + '/../lib')
+require 'dm-forms'
+require 'benchmark'
+require 'dm-core'
+require 'dm-validations'
+DataMapper.setup :default, 'sqlite3::memory:'
+include DataMapper::Form::ModelElements
+
+#--
+# Models
+#++
+
+class User
+  include DataMapper::Resource
+  property :id,    Serial
+  property :name,  String, :format => /^[\w]+$/
+  property :email, String, :format => :email_address
+end
+
+DataMapper.auto_migrate!
+
+$user = User.new :name => 'tj', :email => 'invalid email@lame.com'
+
+#--
+# Benchmarks
+#++
+
+puts
+puts 'Single element'
+Benchmark.bm(25) do |x|
+  x.report("10 elements") {
+    10.times do
+      textarea :comments, :value => 'Enter your comments here', :label => 'Comments:', :required => true
+    end
+  }
+  x.report("100 elements") {
+    100.times do
+      textarea :comments, :value => 'Enter your comments here', :label => 'Comments:', :required => true
+    end
+  }
+  x.report("1000 elements") {
+    1000.times do
+      textarea :comments, :value => 'Enter your comments here', :label => 'Comments:', :required => true
+    end
+  }
+end
+
+puts
+puts 'Capture elements within a fieldset'
+Benchmark.bm(25) do |x|
+  x.report("10 elements") {
+    5.times do
+      fieldset :comments do |f|
+        f.textarea :comments, :value => 'Enter your comments here', :label => 'Comments:', :required => true
+      end
+    end
+  }
+  x.report("100 elements") {
+    50.times do
+      fieldset :comments do |f|
+        f.textarea :comments, :value => 'Enter your comments here', :label => 'Comments:', :required => true
+      end
+    end
+  }
+  x.report("1000 elements") {
+    500.times do
+      fieldset :comments do |f|
+        f.textarea :comments, :value => 'Enter your comments here', :label => 'Comments:', :required => true
+      end
+    end
+  }
+end
+
+# Not real-world examples ... just for benchmarking purposes
+puts
+puts 'Entire forms'
+Benchmark.bm(25) do |x|
+  x.report("Login") {
+    form :login do |f|
+      f.textfield :name, :label => 'Username', :required => true
+      f.textfield :email, :label => 'Email', :required => true
+      f.textfield :pass, :label => 'Password', :required => true
+      f.submit :op, :value => 'Login'
+    end
+  }
+  
+  x.report("Register") {
+    form :register do |f|
+      f.fieldset :general do |f|
+        f.textfield :name, :label => 'Username', :required => true
+        f.textfield :email, :label => 'Email', :required => true
+        f.textfield :pass, :label => 'Password', :required => true
+        f.password :pass_confirm
+      end
+      f.fieldset :details do |f|
+        f.textfield :city, :label => 'City'
+        f.textfield :zip, :label => 'Postal Code'
+      end
+      f.fieldset :forums do |f|
+        f.textarea :signature, :label => 'Signature', :description => 'Enter a signature which will appear below your forum posts.'
+      end
+      f.submit :op, :value => 'Register'
+    end
+  }
+end
+
+puts
+puts 'Entires form with #form_for'
+Benchmark.bm(25) do |x|
+  x.report("User") {
+    form_for $user do |f|
+      f.textfield :name, :label => 'Username', :required => true
+      f.textfield :email, :label => 'Email', :required => true
+      f.submit :op, :value => 'Login'
+    end
+  }
+end

data/examples/datamapper.rb

@@ -0,0 +1,37 @@
+
+$:.unshift File.expand_path(File.dirname(__FILE__) + '/../lib')
+require 'dm-forms'
+require 'dm-core'
+require 'dm-validations'
+
+include DataMapper::Form::ModelElements
+DataMapper.setup :default, 'sqlite3::memory:'
+
+class User
+  include DataMapper::Resource
+  property :id,    Serial
+  property :name,  String, :format => /^[\w]+$/
+  property :email, String, :format => :email_address
+end
+
+DataMapper.auto_migrate!
+user = User.new :name => 'tj', :email => 'invalid email@lame.com'
+
+s = errors_for(user)
+s << form_for(user, :action => '/user') do |f|
+  f.textarea :name
+  f.textarea :email
+  f.submit :op, :value => 'Add'
+end
+puts s
+
+user.email = 'tj@vision-media.ca'
+user.save
+
+s = errors_for(user)
+s << form_for(user, :action => '/user') do |f|
+  f.textarea :name, :label => 'Name'
+  f.textarea :email, :label => 'Email'
+  f.submit :op, :value => 'Update'
+end
+puts s

data/examples/elements.rb

@@ -0,0 +1,31 @@
+
+$:.unshift File.expand_path(File.dirname(__FILE__) + '/../lib')
+require 'dm-forms'
+
+include DataMapper::Form::Elements
+
+def example before, &block
+  puts before << "\n\n"
+  puts yield.gsub!(/^/, '    ')
+  puts
+end
+
+example %(textarea :comments) do
+  textarea :comments
+end
+
+example %(textarea :comments, :label => 'Comments', :description => 'Tell us what you think') do
+  textarea :comments, :label => 'Comments', :description => 'Tell us what you think'
+end
+
+example %(textfield :email, :label => 'Email', :required => true) do
+  textfield :email, :label => 'Email', :required => true
+end
+
+example 'Login' do
+  form :login do |f|
+    f.textfield :name, :label => 'Username'
+    f.textfield :pass, :label => 'Password'
+    f.submit :op, :value => 'Login'
+  end
+end

data/examples/haml.rb

@@ -0,0 +1,21 @@
+
+$:.unshift File.expand_path(File.dirname(__FILE__) + '/../lib')
+require 'rubygems'
+require 'haml'
+require 'dm-forms'
+
+include DataMapper::Form::ModelElements
+
+# Haml does not play very nice with nested Ruby, but then again
+# there is relatively nothing that cannot be altered via styling
+# so placing forms directly within a Haml view is not entirely
+# necessary.
+def login_form
+  form :login, :action => '/user' do |f|
+	  f.textarea :name, :label => 'Name'
+	  f.textarea :email, :label => 'Email'
+	  f.submit :op, :value => 'Login'
+	end
+end
+
+puts Haml::Engine.new(File.read(File.dirname(__FILE__) + '/login.haml')).render

data/examples/login.haml

@@ -0,0 +1,4 @@
+#primary
+  .content
+    %h1 Login
+    = login_form

data/lib/dm-forms/core_ext.rb

@@ -0,0 +1,39 @@
+
+class NilClass
+  def to_xml_attributes #:nodoc:
+    ''
+  end
+  alias :to_html_attributes :to_xml_attributes
+end
+
+class String
+    
+  ##
+  # Convert to a human readable string.
+  #
+  # === Examples:
+  #    
+  #   'im_a_simple.String'.humanize # => 'im a simple String'
+  #
+  
+  def humanize
+    gsub(/[^a-zA-Z\d]/, ' ') || self
+  end
+  
+  ##
+  # Indent a string with pseudo +tabs+ (spaces). Defaults to a single tab.
+  
+  def indent tabs = 1 
+    gsub /^/, '  ' * tabs
+  end
+end
+
+class Symbol
+  
+  ##
+  # Convert to a human readable string. See String#humanize
+  
+  def humanize
+    to_s.humanize
+  end
+end

data/lib/dm-forms/elements.rb

@@ -0,0 +1,210 @@
+
+module DataMapper
+  module Form
+    module Elements
+      
+      ##
+      # Proxy object for capturing elements. See Elements#capture_elements.
+      
+      class Proxy
+        def initialize model = nil
+          @model = model 
+        end
+        
+        def method_missing meth, *args, &block
+          add_error_class_to args if has_a_model_with_errors_on? args.first
+          (@elements ||= []) << Elements.send(meth, *args, &block)
+        end
+        
+        def add_error_class_to args
+          ((args[1] ||= {})[:class] ||= '') << ' error'
+        end
+        
+        def has_a_model_with_errors_on? meth
+          @model and !@model.valid? and @model.errors.on meth
+        end
+      end
+      
+      module_function
+      
+      ##
+      # Generates a generic HTML +name+ tag. Although this method is 
+      # generally used internally by dm-forms, you may utilize it directly
+      # passing any of the following +options+.
+      #
+      # === Options:
+      #
+      #   :self_closing   Wither or not the element should self-close (<br />)
+      #   :attributes     Hash of attributes such as :type => :textfield
+      #
+      
+      def tag name, options = {}, &block
+        Tag.new(name, options, &block).render
+      end
+      
+      ##
+      # Generates a label.
+      
+      def label value, options = {}
+        value << ':'
+        value << '<em>*</em>' if options.delete :required
+        %(<label for="#{options[:for]}">#{value}</label>\n)
+      end
+      
+      ##
+      # Generates a legend.
+      
+      def legend value
+        %(<legend>#{value}</legend>)
+      end
+      
+      ##
+      # Generates a description.
+      
+      def desc text
+        %(\n<p class="description">#{text}</p>) unless text.blank?
+      end
+           
+      ##
+      # Generates an option.
+      
+      def option value, title
+        %(<option value="#{value}">#{title}</option>\n)
+      end
+      
+      ##
+      # Generates a form.
+      
+      def form name, options = {}, &block
+        options = { :method => :post, :id => "form-#{name}" }.merge options
+        unless valid_http_verb? options
+          old_value = options[:value] || ''
+          options[:value] = hidden_method(options[:method]) << old_value
+          options[:method] = :post
+        end
+        tag :form, :attributes => options, &block
+      end
+      
+      ##
+      # Generates a fieldset.
+      
+      def fieldset name, options = {}, &block
+        legend_value = options.has_key?(:legend) ? options.delete(:legend) : name.humanize.capitalize
+        options = { :class => "fieldset-#{name}" }.merge options
+        options[:value] = "\n" << legend(legend_value) << (options.delete(:value) || '')
+        tag :fieldset, :attributes => options, &block
+      end
+              
+      ##
+      # Generates a textfield.
+      
+      def textfield name, options = {}
+        options = { :type => :textfield, :name => name }.merge options
+        tag :input, :self_closing => true, :attributes => options
+      end
+      
+      ##
+      # Generates a password field.
+      
+      def password name, options = {}
+        options = { :type => :password, :name => name }.merge options
+        tag :input, :self_closing => true, :attributes => options
+      end
+      
+      ##
+      # Generates a checkbox.
+      
+      def checkbox name, options = {}
+        options = { :type => :checkbox, :name => name }.merge options
+        tag :input, :self_closing => true, :attributes => options        
+      end
+      
+      ##
+      # Generates a hidden field.
+      
+      def hidden name, options = {}
+        options = { :type => :hidden, :name => name }.merge options
+        tag :input, :self_closing => true, :attributes => options        
+      end
+      
+      ##
+      # Creates hidden _method, with value of +method+.
+      
+      def hidden_method method
+        hidden :_method, :value => method
+      end
+            
+      ##
+      # Generates a radio button.
+      
+      def radio name, options = {}
+        options = { :type => :radio, :name => name }.merge options
+        tag :input, :self_closing => true, :attributes => options        
+      end
+      
+      ##
+      # Generates a file field.
+      
+      def file name, options = {}
+        options = { :type => :file, :name => name }.merge options
+        tag :input, :self_closing => true, :attributes => options        
+      end
+      
+      ##
+      # Generates a select field.
+      
+      def select name, options = {}, &block
+        options = { :name => name, :value => "\n" }.merge options
+        options[:value] << capture_elements(&block) if block_given?
+        options[:value] << select_options(options) if options.include? :options
+        tag :select, :attributes => options
+      end
+      
+      ##
+      # Generates a textarea.
+      
+      def textarea name, options = {}, &block
+        options = { :name => name }.merge options
+        tag :textarea, :attributes => options, &block
+      end
+            
+      ##
+      # Generates a submit button.
+      
+      def submit name, options = {}
+        options = { :type => :submit, :name => name }.merge options
+        tag :input, :self_closing => true, :attributes => options
+      end
+      
+      ##
+      # Generates a button.
+      
+      def button name, options = {}
+        type = options.has_key?(:src) ? :image : :button
+        options = { :type => type, :name => name }.merge options
+        tag :input, :self_closing => true, :attributes => options
+      end
+      
+      ##
+      # Capture results of elements called within +block+. Optionally
+      # a DataMapper model may be passed, at which point error classes
+      # will be applied to invalid elements.
+      
+      def capture_elements model = nil, &block
+        elements = yield Proxy.new(model)
+        elements.join
+      end
+      
+      private
+      
+      def select_options options #:nodoc:
+        options.delete(:options).collect { |value, title| option(value, title) }.join
+      end
+      
+      def valid_http_verb? options #:nodoc:
+        [:get, :post].include? options[:method]
+      end
+      
+    end
+  end
+end

data/lib/dm-forms/model_elements.rb

@@ -0,0 +1,33 @@
+
+module DataMapper
+  module Form
+    module ModelElements
+      
+      include Elements
+      
+      ##
+      # Generates a form.
+      
+      def form_for model, options = {}, &block
+        id = model.class.to_s.downcase
+        method = model.new_record? ? :post : :put
+        options = { :model => model, :method => method }.merge options
+        form id, options, &block
+      end
+      
+      ##
+      # Return markup for errors on +model+.
+      
+      def errors_for model
+        if not model.all_valid?
+          s = %(<ul class="messages error">\n)
+          s << model.errors.collect { |error| "<li>#{error.first}</li>" }.join("\n") 
+          s << "\n</ul>\n"
+        else
+          ''
+        end
+      end
+      
+    end
+  end
+end