RubyGems - formless - Versions diffs - 0.1 - Mend

formless 0.1

Files changed (10) hide show

checksums.yaml ADDED

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 81893b813f0da1305af226192c0715a5f63f883e
+  data.tar.gz: 9e2b6cc25e49ad246db6e6519862378d8a4fbd15
+SHA512:
+  metadata.gz: 2161405866eb39ee0dc998818e8ea848b5d48b511a48a279627ddaa53bd21e763f51f2709b0dc2ca9a5db1c1ed150e3153c67c4a7e162cf991d42ae197808c4e
+  data.tar.gz: 3a6230c67266f323827608a1ff9baa2f2cacba1fa18cdf36fda32e7b8785eb11f8e76fdf7f6e2ed5e55e7d373570a0b34de695cfc13eb0d9e200782b1ed59906

data/Gemfile ADDED

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+gem 'nokogiri', '>=1.5'

data/README.md ADDED

@@ -0,0 +1,74 @@
+Formless
+========
+Formless provides a means to populate forms without the need for anything other than plain-old HTML. It removes the requirement for form population logic within your views, serving as a complete replacement for form builders.
+Formless can be used with any existing libraries or frameworks. Its only dependancy is Nokogiri.
+In Action
+---------
+Install it...
+    gem install formless
+Take some HTML...
+    <!DOCTYPE html>
+    <html>
+      <body>
+        <h1>Edit Person</h1>
+        <form id="edit_form" method="POST" action="./">
+          <input type="text" name="full_name" />
+          <input type="number" min="0" name="age" />
+          <label><input type="radio" name="gender" value="m"> Male</label>
+          <label><input type="radio" name="gender" value="f"> Female</label>
+          <select name="region">
+            <option>America</option>
+            <option>Europe</option>
+            <option>Oceania</option>
+          </select>
+          <input type="submit" value="Submit" />
+        </form>
+      </body>
+    </html>
+And populate it...
+    selector = '#edit_form'
+    values = {name: 'Jeffrey', age: 29, gender: 'm', region: 'Europe'}
+    FormPopulator.new('<html>...</html>', selector).populate!(values).to_s #=> <!DOCTYPE html><html> ... </html>
+How It Works
+------------
+Nokogiri is used to parse the given HTML into a data structure that can be easily and reliably operated on. The keys in the provided hash are mapped to the `name` attribute of HTML elements. A collection of _field setters_, defaulting to `Formless::FieldSetters` are responsible for correctly setting the various field types, whilst _formatters_, defaulting to `Formless::Formatters` provide an opportunity to process the value before setting it, such as formatting dates.
+Performance
+-----------
+Convenience is prioritised over performance; there are many less convenient but better performing solutions if that's your priority. With that said, there are ways to optimise your use of Formless. The most obvious optimisation is to re-use your Formless or Nokogiri NodeSet instances, to save re-parsing your HTML:
+    @form ||= Formless.new('...')
+    @form.populate({name: 'Bill', age: 31}).to_s #=> <!DOCTYPE html><html> ... </html>
+Formless also provides two complementary `populate` methods. `populate!` modifies the nodeset associated with the Formless instance, whilst `populate` works on a copy of that nodeset. Where performance is important, `populate!` should be used. It's important to note however that you must explicitly set a field to a value for that field to be reset, so extra care must be taken:
+    @form ||= Formless.new('...')
+    @form.populate!({name: 'Bill', age: 31})
+    @form.populate!({name: 'John'}) #=> Age is still set to 31
+    @form.populate!({name: 'John', age: nil}) #=> Age is now set to empty
+Comprehensive
+-------------
+Formless is intended to provide comprehensive support for HTML5 forms. Any contradiction to this is considered a bug. To summarise:
+* All HTML5 input fields, including:
+    * Checkboxes
+    * Radio buttons
+    * Password's which are not populated by default
+    * Date and time fields: date, datetime, datetime-local, week, month
+* Textarea fields
+* Select fields, including multi-select fields
+* Common-name fields, such as for use with the array idiom, e.g. name="favourites[]"

data/config.ru ADDED

@@ -0,0 +1,8 @@
+require './lib/formless'
+run proc { |env|
+  request = Rack::Request.new(env)
+  html = open('./spec/form.html').read
+  form = Formless.new(html)
+  [200, {}, [form.populate(request.POST).to_s]]
+}

data/formless.gemspec ADDED

@@ -0,0 +1,18 @@
+$LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
+require 'formless'
+Gem::Specification.new 'formless', Formless::VERSION do |s|
+  s.summary           = "Unobtrusive form populator for web applications."
+  s.description       = "Completely transparent, unobtrusive form populator for web applications and content scrapers."
+  s.authors           = ["Tom Wardrop"]
+  s.email             = "tom@tomwardrop.com"
+  s.homepage          = "http://github.com/wardrop/Formless"
+  s.files             = Dir.glob(`git ls-files`.split("\n") - %w[.gitignore])
+  s.test_files        = Dir.glob('spec/**/*_spec.rb')
+  s.rdoc_options      = %w[--line-numbers --inline-source --title Scorched --encoding=UTF-8]
+  s.required_ruby_version = '>= 1.9.3'
+  s.add_dependency 'nokogiri', '~> 1.5'
+  s.add_development_dependency 'rspec', '~> 2.9'
+end

data/lib/formless.rb ADDED

@@ -0,0 +1,125 @@
+require 'date'
+require 'nokogiri'
+class Formless
+  VERSION = '0.1'
+  DATE_FORMAT = '%d/%m/%Y'
+  DATETIME_FORMAT = '%d/%m/%Y %l:%M%P'
+  FieldSetters = {
+    textarea: proc { |node, values|
+      node.content = values.shift
+    },
+    radio: proc { |node, values|
+      node.delete('checked')
+      node['checked'] = 'checked' if values.include? node['value']
+    },
+    checkbox: proc { |node, values|
+      node.delete('checked')
+      node['checked'] = 'checked' if values.include? node['value']
+    },
+    select: proc { |node, values|
+      matches = node.css('option').to_a.each { |n| n.delete('selected') }.find_all do |n|
+        n.has_attribute?('value') ? values.include?(n['value']) : values.include?(n.content)
+      end
+      if !matches.empty?
+        if node.has_attribute? 'multiple'
+          matches.each { |n| n['selected'] = 'selected' }
+        else
+          matches.first['selected'] = 'selected'
+        end
+      elsif !node.has_attribute?('multiple') && value = values.compact.first
+        node << node.document.create_element('option', value, selected: 'selected')
+      end
+    },
+    password: proc { |node, values|
+      node['value'] = values.shift if options[:populate_passwords]
+    },
+    default: proc { |node, values|
+      node['value'] = values.shift
+    }
+  }
+  Formatters = {
+    [Date, Time] => proc { |node, value|
+      case node['type']
+      when 'date'
+        value.strftime('%F')
+      when 'datetime'
+        value.strftime('%FT%T%z')
+      when 'datetime-local'
+        value.strftime('%FT%T')
+      when 'week'
+        value.strftime('%G-W%V')
+      when 'month'
+        value.strftime('%G-%m')
+      else
+        (value.respond_to? :hour) ? value.strftime(DATETIME_FORMAT) : value.strftime(DATE_FORMAT)
+      end
+    },
+    nil => proc { '' }
+  }
+  attr_accessor :selector
+  attr_reader :options
+  attr_reader :nodeset
+  def nodeset=(html)
+    @nodeset = case html
+    when Nokogiri::XML::Node
+      Nokogiri::XML::NodeSet.new(html, [html])
+    when Nokogiri::XML::NodeSet
+      html
+    else
+      doc = Nokogiri.parse(html)
+      Nokogiri::XML::NodeSet.new(doc, [doc])
+    end
+  end
+  def initialize(html, selector = nil, **options)
+    self.nodeset = html
+    self.selector = selector
+    @options = {
+      field_setters: FieldSetters,
+      formatters: Formatters,
+      populate_passwords: false
+    }.merge!(options)
+  end
+  def field_setters
+    self.options[:field_setters]
+  end
+  def formatters
+    self.options[:formatters]
+  end
+  def populate(values, selector = nil, nodeset = self.nodeset)
+    populate!(values, selector, Nokogiri::XML::NodeSet.new(nodeset.document, nodeset.to_a.map! { |n| n.dup }))
+  end
+  def populate!(values, selector = nil, nodeset = self.nodeset)
+    nodeset = selector ? nodeset.css(selector) : nodeset
+    values.each do |field, value|
+      nodes = nodeset.css(%{[name="#{field}"]})
+      nodes = nodeset.css(%{[name="#{field}[]"]}) if nodes.empty?
+      nodes.each { |n| set_field(n, value) }
+    end
+    nodeset
+  end
+private
+  def set_field(node, value)
+    setter = field_setters[(node['type'] || node.name).to_sym] || FieldSetters[:default]
+    instance_exec(node, [*format_value(node, value)], &setter)
+  end
+  def format_value(node, value)
+    condition, formatter = formatters.find do |conditions, block|
+      [*conditions].find { |c| c === value }
+    end
+    formatter ? instance_exec(node, value, &formatter) : value
+  end
+end

data/spec/form.html ADDED

@@ -0,0 +1,45 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+    <style>
+      label {  display: block; }
+    </style>
+  </head>
+  <body>
+    <h1>Edit Person</h1>
+    <form id="edit_form" method="POST" action="./">
+      <label>Password: <input type="password" name="password"></label>
+      <label>Unknown: <input type="unknown" name="unknown"></label>
+      <label>Full Name: <input type="text" name="full_name"></label>
+      <label>Age: <input type="number" min="0" name="age"></label>
+      <label><input type="radio" name="gender" value="m"> Male</label>
+      <label><input type="radio" name="gender" value="f"> Female</label>
+      <label>Region:
+        <select name="region">
+          <option>America</option>
+          <option>Europe</option>
+          <option value="Australia">Oceania</option>
+        </select>
+      </label>
+      <label>Foods:
+        <select name="foods[]" multiple>
+          <option>Pizza</option>
+          <option>Burger</option>
+          <option>Chips</option>
+        </select>
+      </label>
+      <textarea name="hobbies"></textarea>
+      <label>Birthday: <input type="date" name="birthday"></label>
+      <label>Breakfast: <input type="datetime" name="breakfast"></label>
+      <label>Dinner: <input type="datetime-local" name="dinner"></label>
+      <label>Favourite Week: <input type="week" name="favourite_week"></label>
+      <label>Favourite Month: <input type="month" name="favourite_month"></label>
+      <label><input type="checkbox" name="colours[]" value="red">Red</label>
+      <label><input type="checkbox" name="colours[]" value="green">Green</label>
+      <label><input type="checkbox" name="colours[]" value="blue">Blue</label>
+      <label><input type="checkbox" name="subscribe" value="yes"> Subscribe</label>
+      <div><input type="submit" value="Submit"></div>
+    </form>
+  </body>
+</html>

data/spec/formless_spec.rb ADDED

@@ -0,0 +1,135 @@
+require_relative './helper.rb'
+describe Formless do
+  it "can take a html string" do
+    form = Formless.new(html)
+    form.nodeset.should be_a(Nokogiri::XML::NodeSet)
+    form.nodeset.to_s.strip.should == html.strip
+  end
+  it "can take a nokogiri node" do
+    doc = Nokogiri.parse(html)
+    form = Formless.new(doc)
+    form.nodeset.should be_a(Nokogiri::XML::NodeSet)
+    form.nodeset.document.should == doc
+    form.nodeset[0].should == doc
+  end
+  it "can take a nokogiri nodeset" do
+    nodeset = Nokogiri.parse(html).css('> *')
+    form = Formless.new(nodeset)
+    form.nodeset.should == nodeset
+  end
+  let(:form) do
+    Formless.new(html)
+  end
+  describe "field populating" do
+    example "default/unknown" do
+      form.populate(unknown: 'yay').css('[name=unknown]')[0]['value'].should == 'yay'
+    end
+    example "text" do
+      form.populate(full_name: 'William Fisher').css('[name=full_name]')[0]['value'].should == 'William Fisher'
+    end
+    example "textarea" do
+      form.populate(hobbies: 'fishing, camping').css('[name=hobbies]')[0].content.should == 'fishing, camping'
+    end
+    example "radio" do
+      form.populate(gender: 'f').css('[name=gender][value=f]')[0].has_attribute?('checked').should == true
+    end
+    example "checkbox" do
+      form.populate(subscribe: 'yes').css('[name=subscribe]')[0].has_attribute?('checked').should == true
+    end
+    example "select" do
+      form.populate(region: 'Europe').
+        css('[name=region] > option').find { |n| n.has_attribute?('selected') }.text.should == 'Europe'
+      form.populate(region: 'Australia').
+        css('[name=region] > option').find { |n| n.has_attribute?('selected') }.text.should == 'Oceania'
+      # Will add non-existant values
+      form.populate(region: 'Middle East').
+        css('[name=region] > option').find { |n| n.has_attribute?('selected') }.text.should == 'Middle East'
+    end
+    example "multi-select" do
+      # Also tests order independance
+      form.populate('foods[]' => ['Chips', 'Pizza']).css('[name="foods[]"] > option').select { |n|
+        n.has_attribute?('selected')
+      }.map { |v| v.text }.should == ['Pizza', 'Chips']
+      # Will automatically append square brackets if not found.
+      form.populate('foods' => ['Pizza', 'Chips']).css('[name="foods[]"] > option').select { |n|
+        n.has_attribute?('selected')
+      }.map { |v| v.text }.should == ['Pizza', 'Chips']
+    end
+    example "date" do
+      date = Date.today
+      form.populate(birthday: date).css('[name=birthday]')[0]['value'].should == date.strftime('%F')
+    end
+    example "datetime" do
+      time = DateTime.now
+      form.populate(breakfast: time).css('[name=breakfast]')[0]['value'].should == time.strftime('%FT%T%z')
+    end
+    example "datetime-local" do
+      time = DateTime.now
+      form.populate(dinner: time).css('[name=dinner]')[0]['value'].should == time.strftime('%FT%T')
+    end
+    example "month" do
+      time = DateTime.new(2013, 9, 2, 11, 30, 15)
+      form.populate(favourite_month: time).css('[name=favourite_month]')[0]['value'].should == '2013-09'
+    end
+    example "week" do
+      time = DateTime.new(2013, 9, 2, 11, 30, 15)
+      form.populate(favourite_week: time).css('[name=favourite_week]')[0]['value'].should == '2013-W36'
+    end
+    example "array-like field names" do
+      form.populate('colours[]' => %w{blue red}).css('[name="colours[]"][checked=checked]').map { |n| n['value'] }.should == ['red', 'blue']
+    end
+  end
+  it "outputs a Nokogiri nodeset" do
+    form.populate({}).should be_a(Nokogiri::XML::NodeSet)
+  end
+  it "can modify the original nodeset, or a copy" do
+    form.populate!({full_name: 'Bob Bobinski'}).css('[name=full_name]')[0]['value'].should == 'Bob Bobinski'
+    form.populate({full_name: 'Harold Haroldo'}).css('[name=full_name]')[0]['value'].should == 'Harold Haroldo'
+    form.populate!({}).css('[name=full_name]')[0]['value'].should == 'Bob Bobinski'
+  end
+  it "can take a CSS selector to narrow the nodeset" do
+    form.populate!({full_name: 'Tony Jones', hobbies: 'stuff'}, 'input')
+    form.nodeset.css('[name=full_name]')[0]['value'].should == 'Tony Jones'
+    form.nodeset.css('[name=hobbies]')[0].content.should_not == 'stuff'
+  end
+  describe "configuration" do
+    it "can toggle whether password fields are populated" do
+      form.populate(password: 'ilovemonkeys').css('[name=password]')[0]['value'].should == nil
+      form.options[:populate_passwords] = true
+      form.populate(password: 'ilovemonkeys').css('[name=password]')[0]['value'].should == 'ilovemonkeys'
+    end
+    it "allows field setters to be overridden" do
+      form.options[:field_setters] = Formless::FieldSetters.merge(password: proc { |node| node['value'] = 'meow' })
+      form.populate(password: 'ilovemonkeys').css('[name=password]')[0]['value'].should == 'meow'
+    end
+    it "allows formatters to be overridden" do
+      form.options[:formatters] = Formless::Formatters.merge('yes' => proc { |n,v| v == 'yes' ? 1 : 0 })
+      form.populate({full_name: 'yes'}).css('[name=full_name]')[0]['value'].should == '1'
+    end
+  end
+end

data/spec/helper.rb ADDED

@@ -0,0 +1,15 @@
+require 'rack/test'
+require_relative '../lib/formless.rb'
+module GlobalConfig
+  extend RSpec::SharedContext
+  let(:html) do
+    open(File.join __dir__, 'form.html').read
+  end
+end
+RSpec.configure do |c|
+  c.alias_example_to :they
+  # c.backtrace_clean_patterns = []
+  c.include GlobalConfig
+end

metadata ADDED

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: formless
+version: !ruby/object:Gem::Version
+  version: '0.1'
+platform: ruby
+authors:
+- Tom Wardrop
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2013-04-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.9'
+description: Completely transparent, unobtrusive form populator for web applications
+  and content scrapers.
+email: tom@tomwardrop.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- README.md
+- config.ru
+- formless.gemspec
+- lib/formless.rb
+- spec/form.html
+- spec/formless_spec.rb
+- spec/helper.rb
+homepage: http://github.com/wardrop/Formless
+licenses: []
+metadata: {}
+post_install_message:
+rdoc_options:
+- --line-numbers
+- --inline-source
+- --title
+- Scorched
+- --encoding=UTF-8
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project:
+rubygems_version: 2.0.0
+signing_key:
+specification_version: 4
+summary: Unobtrusive form populator for web applications.
+test_files:
+- spec/formless_spec.rb