campo 0.3.4 → 0.9.0

data/.gitignore

@@ -15,3 +15,6 @@ scratch/
 coverage/
 .yardoc/
 docs/
+vendor/
+bin/
+Gemfile.lock

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format nested

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 1.9.2
+  - 1.9.3
+  - ruby-head
+bundler_args: --binstubs --path vendor 
+script: bundle exec rspec spec

data/{CHANGES → CHANGES.markdown}

@@ -1,3 +1,65 @@
+## v0.9.0 16th of June 2012 ##
+
+* Updated the README with info on using plugins, and how to contribute.
+* `describe` in the Aria plugin no longer needs a tuple to create a list, it can take an array of single valued arrays as the missing part of the tuple will default to an empty hash.
+* Added testing for the develop branch to Travis.
+* Moved most of the code to a separate file that is then required back in by lib/campo.rb, as specs were affected by the order they were run in. Now, each spec only `require` the files it needs and clear the plugins before running, which means they can be run in any order and not be affected.
+
+----
+
+## v0.8.3b 14th of May 2012 ##
+
+* `with_default` can now have the 'disabled' attribute turned off. 
+* Added a lot of docs.
+
+----
+
+v0.8.2b Literals can have attributes passed. Aria plugin's `describe` can take a list of messages and create an unordered list.
+
+v0.8.1b Added a Rakefile with a task to generate the docs, for convenience. Fixed a couple of typos in the docs.
+
+v0.8.0b The Aria plugin's `describe` now takes options for adding attributes.
+
+v0.7.1b Removed debugging statement that was being output.
+
+v0.7.0b Use of [] in input names now allowed, for grouping inputs like an array.
+
+v0.6.14b Lowercased aria.rb for bundler.
+
+v0.6.12b Another mistake, an accidental move of a file - this will teach me to run the specs even for trivial changes!
+
+v0.6.11b My mistake this time, not using lowercase for the file names was causing a problem deploying to Heroku.
+
+v0.6.10b Removed ENV vars from gemspec as deployment to Heroku with Bundler is problematic.
+
+v0.6.7b Added `describe` method, via the Aria plugin. It will help to keep the forms accessible.
+
+v0.6.6b Validation rules are now built. Validations for required, digits and maxlength added.
+
+v0.6.5b Labels get the "required" class too when using JQueryValidation, to make all our styling wishes come true!
+
+v0.6.4b Default option for select tags now has its id attribute appended with "_default" to stop the id clashing with the select tag.
+
+v0.6.3b Convenience method `submit` is now more convenient as it takes the value as part of the hash args without a pesky unused parameter getting in the way.
+
+v0.6.2b Added easier labelling for textareas.
+
+v0.6.1b The function for the JQuery validation wasn't right, fixed it now, and updated the specs a little for it.
+
+v0.6.0b All form fields get an id. Added "hidden" input convenience method.
+
+v0.5.2b Turns out that you can learn a lot if you run the specs, such as inners didn't need changing to default_proc, just atts.
+
+v0.5.1b Hash defaults for form should work better now as moved to using Hash#default_proc which updates the key the way required.
+
+v0.5.0b Added a JQuery validation plugin.
+
+v0.4.0b Added an outputter class, currently hidden under old API. Improved argument passing, added before and after hooks for output. Extra args to Campo.output are now passed as options, and partials are done this way too instead of the clumsy prepended argument.
+
+v0.3.6b removed need for block variables.
+
+v0.3.5b Changed tabindex to use an instance variable, so now forms should be able to be nested and the tabindex update properly.
+
 v0.3.4 Added `password` convenience method.
 
 v0.3.2 Blocks are now passed on for .literal and .bit_of_ruby

data/Gemfile

@@ -0,0 +1,15 @@
+source "https://rubygems.org"
+
+group :development do
+  gem "rake"
+  gem "yard"
+  gem "maruku"
+  gem "wirble"
+  gem "reek"
+end
+
+group :testing do
+  gem "rspec"
+  gem "simplecov"
+  gem "haml"
+end

data/README.markdown

@@ -1,3 +1,5 @@
+[![Build Status for development branch](https://secure.travis-ci.org/yb66/Campo.png?branch=develop)](http://travis-ci.org/yb66/Campo)
+
 # Campo #
 
 A static dynamic form builder into haml. Yep, static _and_ dynamic. Use it to statically create a form into haml, but you may notice it's taken advantage of haml's "add a hash to the front of the attributes and it'll get merged" property. [See Haml docs for more](http://haml-lang.com/docs/yardoc/file.HAML_REFERENCE.html#attribute_methods). More on that below.
@@ -6,8 +8,15 @@ Btw, I'll be using this with Sinatra, if you're using Rails you'll need to work
 
 ## Note! ##
 
-As always, keep in mind this is an open source project (licence below) and you can contribute! If you find a problem or would like a feature changed or added, let me know, or even better, fork the project and send me a pull request.
+As always, keep in mind this is an open source project (licence below) and you can contribute! If you find a problem or would like a feature changed or added, let me know, or even better, fork the project and send me a pull request. See the "Contributing" section for some notes on how to do that.
+
+## Double note! ##
+
+I use Campo myself, and I'm trying to improve it. As I don't want to push new stuff out before I've had a chance to give it a whirl and see if it makes sense and works (through experience, specs aren't everything) I'll have several versions of this up here, some unreleased. I tend to append a 'b' to the end of an unreleased version. Please make sure you're reading the documentation for the version you're using!
 
+## Version numbers ##
+
+You'll notice this library is well past version 0.0.1. Some people take this to mean something like "it works brilliantly", but in fact, I'm attempting to use the [semver standard](http://semver.org/). In essence, it tells you about changes to the API, not about code quality - that's what the specs/tests are for. It's worth a read.
 
 ## Why write this? ##
 
@@ -22,124 +31,79 @@ Here's an example form:
 
     # Now starts the real action #
     
-    form = Campo.form "myform", action: "/my/form/update/"
-
-    form.fieldset "Your details" do |f|
-      f.text "full_name",  size: 60 
-      f.text "dob", "Date of birth: ", size: 8
-      
-      f.select( "gender_id", {opts: genders }).with_default.labelled( "Gender: " )
-      
-      f.select "teas" do |s|
-        s.with_default
-        s.option("ceylon")
-        s.option("breakfast")
-        s.option("earl grey")
-        s.option("oolong")
-        s.option("sencha")
-      end.labelled "Favourite tea:"
-      
-      f.text "occupation", "Occupation: ", size: 60  
-      f.text "phone_landline", "Phone  landline : ", size: 20  
-      f.text "phone_mobile", "Phone  mobile : ", size: 20  
-
-      f.submit "Save"
-  
+    form = Campo.form "personal_details", action: %Q!"uri("/my/personal_details/update/")!  do
+      fieldset "Your details" do              
+        text "full_name", "Full name: ", size: 60 
+        text "dob", "Date of birth: ", size: 10  #TODO change this
+        fieldset "Gender: "  do
+          radio "gender", "Male", value: 1 
+          radio "gender", "Female", value: 2 
+        end
+        select("teas").with_default.option("ceylon").option("breakfast").option("earl grey").labelled("Favourite tea:")
+        text "occupation", "Occupation: ", size: 60 
+        text "phone_landline", "Phone (landline): ", size: 20 
+        text "phone_mobile", "Phone (mobile): ", size: 20 
+        fieldset "May we contact you..."  do
+          checkbox "contactable", "In the day?", value: "day" 
+          checkbox "contactable",  "In the evening?", value: "evening" 
+        end
+        submit "Save"
+      end
     end
+    
+    
+    puts Campo.output( form )
 
 and the output:
 
-
-    puts Campo.output( form )
-
     - atts = {} if atts.nil?
-    - atts.default = {} if atts.default.nil?
+    - atts.default_proc = proc {|hash, key| hash[key] = {} } if atts.default_proc.nil?
+    - inners = {} if inners.nil?
     - inners.default = "" if inners.default.nil?
-    - i = 0 # for tabindex
-
-    %form{ atts[:myform], method: "POST", action: "/my/form/update/", name: "myform",  }
+    - @campo_tabindex ||= 0 # for tabindex
+    %form{ atts[:personal_details], id: "personal_details", method: "POST", action: uri("/my/personal_details/update/"), name: "personal_details",  }
       %fieldset{  }
         %legend{  }Your details
         %label{ for: "full_name",  }
           Full name: 
-          %input{ atts[:full_name], tabindex: "#{i += 1}", type: "text", id: "full_name", size: "60", name: "full_name",  }
+          %input{ atts[:full_name], tabindex: "#{@campo_tabindex += 1}", id: "full_name", type: "text", size: "60", name: "full_name",  }
         %label{ for: "dob",  }
           Date of birth: 
-          %input{ atts[:dob], tabindex: "#{i += 1}", type: "text", id: "dob", size: "8", name: "dob",  }
-        %label{ for: "gender_id",  }
-          Gender: 
-          %select{ atts[:gender_id], tabindex: "#{i += 1}", name: "gender_id",  }
-            %option{  value: "", disabled: "disabled", name: "gender_id",  }Choose one:
-            %option{ atts[:gender_id_1], value: "1", id: "gender_id_1", name: "gender_id",  }Male
-            %option{ atts[:gender_id_2], value: "2", id: "gender_id_2", name: "gender_id",  }Female
+          %input{ atts[:dob], tabindex: "#{@campo_tabindex += 1}", id: "dob", type: "text", size: "10", name: "dob",  }
+        %fieldset{  }
+          %legend{  }Gender: 
+          %label{ for: "gender_1",  }
+            Male
+            %input{ atts[:gender_1], tabindex: "#{@campo_tabindex += 1}", id: "gender_1", type: "radio", value: "1", name: "gender",  }
+          %label{ for: "gender_2",  }
+            Female
+            %input{ atts[:gender_2], tabindex: "#{@campo_tabindex += 1}", id: "gender_2", type: "radio", value: "2", name: "gender",  }
         %label{ for: "teas",  }
           Favourite tea:
-          %select{ atts[:teas], tabindex: "#{i += 1}", name: "teas",  }
-            %option{  value: "", disabled: "disabled", name: "teas",  }Choose one:
-            %option{ atts[:teas_ceylon], value: "ceylon", id: "teas_ceylon", name: "teas",  }Ceylon
-            %option{ atts[:teas_breakfast], value: "breakfast", id: "teas_breakfast", name: "teas",  }Breakfast
-            %option{ atts[:teas_earl_grey], value: "earl grey", id: "teas_earl_grey", name: "teas",  }Earl grey
-            %option{ atts[:teas_oolong], value: "oolong", id: "teas_oolong", name: "teas",  }Oolong
-            %option{ atts[:teas_sencha], value: "sencha", id: "teas_sencha", name: "teas",  }Sencha
+          %select{ atts[:teas], tabindex: "#{@campo_tabindex += 1}", id: "teas", name: "teas",  }
+            %option{ atts[:teas], id: "teas", value: "", disabled: "disabled", name: "teas",  }Choose one:
+            %option{ atts[:teas_ceylon], id: "teas_ceylon", value: "ceylon", name: "teas",  }Ceylon
+            %option{ atts[:teas_breakfast], id: "teas_breakfast", value: "breakfast", name: "teas",  }Breakfast
+            %option{ atts[:teas_earl_grey], id: "teas_earl_grey", value: "earl grey", name: "teas",  }Earl grey
         %label{ for: "occupation",  }
           Occupation: 
-          %input{ atts[:occupation], tabindex: "#{i += 1}", type: "text", id: "occupation", size: "60", name: "occupation",  }
+          %input{ atts[:occupation], tabindex: "#{@campo_tabindex += 1}", id: "occupation", type: "text", size: "60", name: "occupation",  }
         %label{ for: "phone_landline",  }
           Phone (landline): 
-          %input{ atts[:phone_landline], tabindex: "#{i += 1}", type: "text", id: "phone_landline", size: "20", name: "phone_landline",  }
+          %input{ atts[:phone_landline], tabindex: "#{@campo_tabindex += 1}", id: "phone_landline", type: "text", size: "20", name: "phone_landline",  }
         %label{ for: "phone_mobile",  }
           Phone (mobile): 
-          %input{ atts[:phone_mobile], tabindex: "#{i += 1}", type: "text", id: "phone_mobile", size: "20", name: "phone_mobile",  }
-        %input{ atts[:Save_Save], tabindex: "#{i += 1}", type: "submit", id: "Save_Save", value: "Save",  }
-
-and that outputs:
-
-    puts Haml::Engine.new( Campo.output( form ) ).render
-    
-    <form action='/my/form/update/' method='POST' name='myform'>
-      <fieldset>
-        <legend>Your details</legend>
-        <label for='full_name'>
-          Full name:
-          <input id='full_name' name='full_name' size='60' tabindex='1' type='text' />
-        </label>
-          Date of birth:
-          <input id='dob' name='dob' size='8' tabindex='2' type='text' />
-        </label>
-        <label for='gender_id'>
-          Gender:
-          <select name='gender_id' tabindex='3'>
-            <option disabled='disabled' name='gender_id' value=''>Choose one:</option>
-            <option id='gender_id_1' name='gender_id' value='1'>Male</option>
-            <option id='gender_id_2' name='gender_id' value='2'>Female</option>
-          </select>
-        </label>
-        <label for='teas'>
-          Favourite tea:
-          <select name='teas' tabindex='4'>
-            <option disabled='disabled' name='teas' value=''>Choose one:</option>
-            <option id='teas_ceylon' name='teas' value='ceylon'>Ceylon</option>
-            <option id='teas_breakfast' name='teas' value='breakfast'>Breakfast</option>
-            <option id='teas_earl_grey' name='teas' value='earl grey'>Earl grey</option>
-            <option id='teas_oolong' name='teas' value='oolong'>Oolong</option>
-            <option id='teas_sencha' name='teas' value='sencha'>Sencha</option>
-          </select>
-        </label>
-        <label for='occupation'>
-          Occupation:
-          <input id='occupation' name='occupation' size='60' tabindex='5' type='text' />
-        </label>
-        <label for='phone_landline'>
-          Phone (landline):
-          <input id='phone_landline' name='phone_landline' size='20' tabindex='6' type='text' />
-        </label>
-        <label for='phone_mobile'>
-          Phone (mobile):
-          <input id='phone_mobile' name='phone_mobile' size='20' tabindex='7' type='text' />
-        </label>
-        <input id='Save_Save' tabindex='8' type='submit' value='Save' />
-      </fieldset>
-    </form>
+          %input{ atts[:phone_mobile], tabindex: "#{@campo_tabindex += 1}", id: "phone_mobile", type: "text", size: "20", name: "phone_mobile",  }
+        %fieldset{  }
+          %legend{  }May we contact you...
+          %label{ for: "contactable_day",  }
+            In the day?
+            %input{ atts[:contactable_day], tabindex: "#{@campo_tabindex += 1}", id: "contactable_day", type: "checkbox", value: "day", name: "contactable",  }
+          %label{ for: "contactable_evening",  }
+            In the evening?
+            %input{ atts[:contactable_evening], tabindex: "#{@campo_tabindex += 1}", id: "contactable_evening", type: "checkbox", value: "evening", name: "contactable",  }
+        %input{ atts[:Save], tabindex: "#{@campo_tabindex += 1}", id: "Save", type: "submit", value: "Save",  }
+
 
 ## Haml attributes ##
 
@@ -151,65 +115,82 @@ These get added to the top when calling `Campo.output`, to provide sane defaults
     - atts.default = {} if atts.default.nil?
     - inners = {} if inners.nil?
     - inners.default = "" if inners.default.nil?
+    - @campo_tabindex ||= 0 # for tabindex
 
 Note: if you don't want these added, you can do:
 
-    Campo.output :partial, your_tag
+    Campo.output name-of-tag-here, :partial => true
     
+e.g
 
-In the select tag (below), notice how each tag gets a local variable added to the front. You can either fill that variable with a hash pair, or an empty hash gets passed and nothing happens.
+    Campo.output form, :partial => true
+    
 
 Here's some Campo code for a select tag with options:
 
-    form = Campo.form "best_bands", action: "/best/bands/" do |form|
-      form.select("bands").option("Suede").option("Blur").option("Oasis").option("Echobelly").option("Pulp").option("Supergrass").with_default.labelled("Favourite band:")
+    form = Campo.form "best_bands", action: "/best/bands/" do
+      select("bands").option("Suede").option("Blur").option("Oasis").option("Echobelly").option("Pulp").option("Supergrass").with_default.labelled("Favourite band:")
     end
     
 or
 
-    form = Campo.form "best_bands", action: "/best/bands/"
-    form.select("bands") do |s|
-      s.with_default
-      s.option("Suede")
-      s.option("Blur")
-      s.option("Oasis")
-      s.option("Echobelly")
-      s.option("Pulp")
-      s.option("Supergrass")
-    end.labelled("Favourite band:")
+    form = Campo.form "best_bands", action: "/best/bands/" do
+      select "bands" do
+        with_default
+        option "Suede"
+        option "Blur"
+        option "Oasis"
+        option "Echobelly"
+        option "Pulp"
+        option "Supergrass"
+      end.labelled("Favourite band:")
+    end
     
 or an array of arrays:
 
-    form = Campo.form "best_bands", action: "/best/bands/"
-    form.select( "bands", opts: [ 
-      ["Suede"],
-      ["Blur"],
-      ["Oasis"],
-      ["Echobelly"],
-      ["Pulp"],
-      ["Supergrass"],
-    ] ).with_default.labelled("Favourite band:")
-
-(or mix and match blocks, .new, arrays and hashes)  
+    form = Campo.form "best_bands", action: "/best/bands/" do
+      select( "bands", opts: [ 
+        ["Suede"],
+        ["Blur"],
+        ["Oasis"],
+        ["Echobelly"],
+        ["Pulp"],
+        ["Supergrass"],
+      ] ).with_default.labelled("Favourite band:")
+    end
+    
+or mix and match blocks, .new, arrays and hashes as you see fit.
 
  
 Generate the haml:
     
-    Campo.output form #
+    Campo.output form
 
 And the Haml generated:
 
-    %form{ atts[:best_bands], method: "POST", action: "/best/bands/", name: "best_bands",  }
+    - atts = {} if atts.nil?
+    - atts.default_proc = proc {|hash, key| hash[key] = {} } if atts.default_proc.nil?
+    - inners = {} if inners.nil?
+    - inners.default = "" if inners.default.nil?
+    - @campo_tabindex ||= 0 # for tabindex
+    %form{ atts[:best_bands], id: "best_bands", method: "POST", action: "/best/bands/", name: "best_bands",  }
       %label{ for: "bands",  }
         Favourite band:
-        %select{ atts[:bands], tabindex: "#{i += 1}", name: "bands",  }
-          %option{  value: "", disabled: "disabled", name: "bands",  }Choose one:
-          %option{ atts[:bands_suede], value: "Suede", id: "bands_suede", name: "bands",  }Suede
-          %option{ atts[:bands_blur], value: "Blur", id: "bands_blur", name: "bands",  }Blur
-          %option{ atts[:bands_oasis], value: "Oasis", id: "bands_oasis", name: "bands",  }Oasis
-          %option{ atts[:bands_echobelly], value: "Echobelly", id: "bands_echobelly", name: "bands",  }Echobelly
-          %option{ atts[:bands_pulp], value: "Pulp", id: "bands_pulp", name: "bands",  }Pulp
-          %option{ atts[:bands_supergrass], value: "Supergrass", id: "bands_supergrass", name: "bands",  }Supergrass
+        %select{ atts[:bands], tabindex: "#{@campo_tabindex += 1}", id: "bands", name: "bands",  }
+          %option{ atts[:bands], id: "bands", value: "", disabled: "disabled", name: "bands",  }Choose one:
+          %option{ atts[:bands_suede], id: "bands_suede", value: "Suede", name: "bands",  }Suede
+          %option{ atts[:bands_blur], id: "bands_blur", value: "Blur", name: "bands",  }Blur
+          %option{ atts[:bands_oasis], id: "bands_oasis", value: "Oasis", name: "bands",  }Oasis
+          %option{ atts[:bands_echobelly], id: "bands_echobelly", value: "Echobelly", name: "bands",  }Echobelly
+          %option{ atts[:bands_pulp], id: "bands_pulp", value: "Pulp", name: "bands",  }Pulp
+          %option{ atts[:bands_supergrass], id: "bands_supergrass", value: "Supergrass", name: "bands",  }Supergrass
+
+
+In the examples above, notice how the output for each tag gets a local variable added to the front. 
+
+> %option{ **atts[:bands_supergrass]**, id: "bands_supergrass", value: "Supergrass", name: "bands",  }Supergrass
+
+You can either fill that variable with a hash pair, or an empty hash gets passed and nothing happens. Read the Haml docs link at the top of the readme for more info.
 
 
 If you wanted to select "Blur" dynamically (and you should, but I'd accept Suede) you might do:
@@ -229,6 +210,11 @@ You can do this with any kind of attribute you wish to add. For example:
 
     atts[:bands_blur] = {not_worth_listening_to: "selected"}
     
+    #=> <option not_worth_listening_to='selected' id='bands_blur' name='bands' value='Blur'>Blur</option>
+    
+But I doubt your name is Noel Gallagher, which makes this a spurious example.
+
+    
 ## Be selective ##
     
     opts = [
@@ -245,16 +231,15 @@ You can do this with any kind of attribute you wish to add. For example:
 Output:
     
     - atts = {} if atts.nil?
-    - atts.default = {} if atts.default.nil?
+    - atts.default_proc = proc {|hash, key| hash[key] = {} } if atts.default_proc.nil?
     - inners = {} if inners.nil?
     - inners.default = "" if inners.default.nil?
-    - i = 0 # for tabindex
-    
-    %form{ atts[:selective_example], method: "POST", name: "selective_example",  }
-      %select{ atts[:teas], tabindex: "#{i += 1}", name: "teas",  }
-        %option{ atts[:teas_ceylon], value: "ceylon", id: "teas_ceylon", name: "teas",  }Ceylon
-        %option{ atts[:teas_english_breakfast], value: "english_breakfast", selected: "selected", id: "teas_english_breakfast", name: "teas",  }English breakfast
-        %option{ atts[:teas_earl_grey], value: "earl_grey", id: "teas_earl_grey", name: "teas",  }Earl grey
+    - @campo_tabindex ||= 0 # for tabindex
+    %form{ atts[:selective_example], id: "selective_example", method: "POST", name: "selective_example",  }
+      %select{ atts[:teas], tabindex: "#{@campo_tabindex += 1}", id: "teas", name: "teas",  }
+        %option{ atts[:teas_ceylon], id: "teas_ceylon", value: "ceylon", name: "teas",  }Ceylon
+        %option{ atts[:teas_english_breakfast], id: "teas_english_breakfast", value: "english_breakfast", selected: "selected", name: "teas",  }English breakfast
+        %option{ atts[:teas_earl_grey], id: "teas_earl_grey", value: "earl_grey", name: "teas",  }Earl grey
         
 ## Pass a hash ##
 
@@ -268,15 +253,15 @@ Output:
     form = Campo.form "simple_hash_example"
     form.select "teas", opts: opts
     
-    Campo.output :partial, form
+    Campo.output form, partial: true
     
 Output:
     
-    %form{ atts[:simple_hash_example], method: "POST", name: "simple_hash_example",  }
-      %select{ atts[:teas], tabindex: "#{i += 1}", name: "teas",  }
-        %option{ atts[:teas_ceylon], value: "ceylon", id: "teas_ceylon", name: "teas",  }Ceylon
-        %option{ atts[:teas_english_breakfast], value: "english_breakfast", id: "teas_english_breakfast", name: "teas",  }English Breakfast
-        %option{ atts[:teas_earl_grey], value: "earl_grey", id: "teas_earl_grey", name: "teas",  }Earl Grey
+    %form{ atts[:simple_hash_example], id: "simple_hash_example", method: "POST", name: "simple_hash_example",  }
+      %select{ atts[:teas], tabindex: "#{@campo_tabindex += 1}", id: "teas", name: "teas",  }
+        %option{ atts[:teas_ceylon], id: "teas_ceylon", value: "ceylon", name: "teas",  }Ceylon
+        %option{ atts[:teas_english_breakfast], id: "teas_english_breakfast", value: "english_breakfast", name: "teas",  }English Breakfast
+        %option{ atts[:teas_earl_grey], id: "teas_earl_grey", value: "earl_grey", name: "teas",  }Earl Grey
 
 With an array for the value:
 
@@ -289,15 +274,15 @@ With an array for the value:
     form = Campo.form "hash_with_array_example"
     form.select "teas", opts: opts
     
-    Campo.output :partial, form
+    Campo.output form, :partial => true
 
 Output:
     
-    %form{ atts[:hash_with_array_example], method: "POST", name: "hash_with_array_example",  }
-      %select{ atts[:teas], tabindex: "#{i += 1}", name: "teas",  }
-        %option{ atts[:teas_ceylon], value: "ceylon", id: "teas_ceylon", name: "teas",  }Ceylon
-        %option{ atts[:teas_english_breakfast], value: "english_breakfast", selected: "selected", id: "teas_english_breakfast", name: "teas",  }English Breakfast
-        %option{ atts[:teas_earl_grey], value: "earl_grey", id: "teas_earl_grey", name: "teas",  }Earl Grey
+    %form{ atts[:hash_with_array_example], id: "hash_with_array_example", method: "POST", name: "hash_with_array_example",  }
+      %select{ atts[:teas], tabindex: "#{@campo_tabindex += 1}", id: "teas", name: "teas",  }
+        %option{ atts[:teas_ceylon], id: "teas_ceylon", value: "ceylon", name: "teas",  }Ceylon
+        %option{ atts[:teas_english_breakfast], id: "teas_english_breakfast", value: "english_breakfast", selected: "selected", name: "teas",  }English Breakfast
+        %option{ atts[:teas_earl_grey], id: "teas_earl_grey", value: "earl_grey", name: "teas",  }Earl Grey
 
 ## Adding in helpers ##
 
@@ -322,40 +307,30 @@ Although, if you forget the "=" sign it will add it for you.
 
 ## And literals ##
 
-It's really just a literal:
+`bit_of_ruby` is really just a literal with a shortcut. Here are some examples using literals:
 
 
-    form = Campo.form "favourite_teas", action: %Q!"uri("/fav/teas/")! do |form|
-      form.select("teas").with_default.option("ceylon").option("breakfast").option("earl grey").labelled("Favourite tea:") 
-      form.literal %Q<%p= "I like tea!">
+    form = Campo.form "favourite_teas", action: %Q!"uri("/fav/teas/")! do
+      select("teas").with_default.option("ceylon").option("breakfast").option("earl grey").labelled("Favourite tea:") 
+      literal %Q<%p= "I like tea!">
     end
-    Campo.output form
+    
+    puts Campo.output form
   
-
-    %form{ atts[:favourite_teas], method: "POST", action: uri("/fav/teas/"), name: "favourite_teas",  }
+    - atts = {} if atts.nil?
+    - atts.default_proc = proc {|hash, key| hash[key] = {} } if atts.default_proc.nil?
+    - inners = {} if inners.nil?
+    - inners.default = "" if inners.default.nil?
+    - @campo_tabindex ||= 0 # for tabindex
+    %form{ atts[:favourite_teas], id: "favourite_teas", method: "POST", action: uri("/fav/teas/"), name: "favourite_teas",  }
       %label{ for: "teas",  }
         Favourite tea:
-        %select{ atts[:teas], tabindex: "#{i += 1}", name: "teas",  }
-          %option{  value: "", disabled: "disabled", name: "teas",  }Choose one:
-          %option{ atts[:teas_ceylon], value: "ceylon", id: "teas_ceylon", name: "teas",  }Ceylon
-          %option{ atts[:teas_breakfast], value: "breakfast", id: "teas_breakfast", name: "teas",  }Breakfast
-          %option{ atts[:teas_earl_grey], value: "earl grey", id: "teas_earl_grey", name: "teas",  }Earl grey
+        %select{ atts[:teas], tabindex: "#{@campo_tabindex += 1}", id: "teas", name: "teas",  }
+          %option{ atts[:teas], id: "teas", value: "", disabled: "disabled", name: "teas",  }Choose one:
+          %option{ atts[:teas_ceylon], id: "teas_ceylon", value: "ceylon", name: "teas",  }Ceylon
+          %option{ atts[:teas_breakfast], id: "teas_breakfast", value: "breakfast", name: "teas",  }Breakfast
+          %option{ atts[:teas_earl_grey], id: "teas_earl_grey", value: "earl grey", name: "teas",  }Earl grey
       %p= "I like tea!"
-      
-    puts Haml::Engine.new( Campo.output form ).render
-    
-    <form action='/fav/teas/' method='POST' name='favourite_teas'>
-      <label for='teas'>
-        Favourite tea:
-        <select name='teas' tabindex='1'>
-          <option disabled='disabled' name='teas' value=''>Choose one:</option>
-          <option id='teas_ceylon' name='teas' value='ceylon'>Ceylon</option>
-          <option id='teas_breakfast' name='teas' value='breakfast'>Breakfast</option>
-          <option id='teas_earl_grey' name='teas' value='earl grey'>Earl grey</option>
-        </select>
-      </label>
-      <p>I like tea!</p>
-    </form>
     
 You can use literals to wrap forms in divs too:
     
@@ -363,46 +338,177 @@ You can use literals to wrap forms in divs too:
       wrapper << form # the form defined already above
     end
     
-    puts Campo.output doc
-    
+    puts Campo.output doc, partial: true
+
     .centred.form
-      %form{ atts[:favourite_teas], method: "POST", action: uri("/fav/teas/"), name: "favourite_teas",  }
+      %form{ atts[:favourite_teas], id: "favourite_teas", method: "POST", action: uri("/fav/teas/"), name: "favourite_teas",  }
         %label{ for: "teas",  }
           Favourite tea:
-          %select{ atts[:teas], tabindex: "#{i += 1}", name: "teas",  }
-            %option{  value: "", disabled: "disabled", name: "teas",  }Choose one:
-            %option{ atts[:teas_ceylon], value: "ceylon", id: "teas_ceylon", name: "teas",  }Ceylon
-            %option{ atts[:teas_breakfast], value: "breakfast", id: "teas_breakfast", name: "teas",  }Breakfast
-            %option{ atts[:teas_earl_grey], value: "earl grey", id: "teas_earl_grey", name: "teas",  }Earl grey
+          %select{ atts[:teas], tabindex: "#{@campo_tabindex += 1}", id: "teas", name: "teas",  }
+            %option{ atts[:teas], id: "teas", value: "", disabled: "disabled", name: "teas",  }Choose one:
+            %option{ atts[:teas_ceylon], id: "teas_ceylon", value: "ceylon", name: "teas",  }Ceylon
+            %option{ atts[:teas_breakfast], id: "teas_breakfast", value: "breakfast", name: "teas",  }Breakfast
+            %option{ atts[:teas_earl_grey], id: "teas_earl_grey", value: "earl grey", name: "teas",  }Earl grey
         %p= "I like tea!"
+
         
 ## tabindex ##
 
-Each field gets `tabindex: "#{i += 1}"` added to its attributes. This will generate a tabindex easily for you.
+Each field gets `@campo_tabindex += 1` added to its attributes. This will generate a tabindex easily for you.
 
-Note: I'm considering making this an instance variable so that it can be passed through easily to nested partials, but I need to test it first.
+Since it's an instance variable it can be passed through easily to nested partials and the count will still be right.
 
 ## Blocks ##
 
-Most fields will accept a block, so you can nest whatever you like. Generally I just use this for forms, fieldsets and selects (and those have specs) but if you want to try something new, do it! Let me know if it breaks.
+Most fields will accept a block, so you can nest whatever you like. Generally I just use this for forms, fieldsets and selects (and those have specs) but if you want to try something new, do it! Let me know if it breaks. You don't have to use the `|var|` notation unless you feel it's helpful.
 
     form = Campo.literal "%div" do |div| 
-      div << Campo.form( "nested" ) do |form|
-        form.fieldset do |f|
-          f.select "blurg" do |s|
-            s.option "oopsie"
-            s.option "daisies"
+      div << Campo.form( "nested" ) do
+        fieldset "Nest" do
+          select "blurg" do
+            option "oopsie"
+            option "daisies"
           end.labelled "splat"
-          f.text "blah"
+          text "blah"
         end
       end
     end
     
+    puts Campo.output form
+
+Output:
+    
+    - atts = {} if atts.nil?
+    - atts.default_proc = proc {|hash, key| hash[key] = {} } if atts.default_proc.nil?
+    - inners = {} if inners.nil?
+    - inners.default = "" if inners.default.nil?
+    - @campo_tabindex ||= 0 # for tabindex
+    %div
+      %form{ atts[:nested], id: "nested", method: "POST", name: "nested",  }
+        %fieldset{  }
+          %legend{  }Nest
+          %label{ for: "blurg",  }
+            splat
+            %select{ atts[:blurg], tabindex: "#{@campo_tabindex += 1}", id: "blurg", name: "blurg",  }
+              %option{ atts[:blurg_oopsie], id: "blurg_oopsie", value: "oopsie", name: "blurg",  }Oopsie
+              %option{ atts[:blurg_daisies], id: "blurg_daisies", value: "daisies", name: "blurg",  }Daisies
+          %label{ for: "blah",  }
+            Blah
+            %input{ atts[:blah], tabindex: "#{@campo_tabindex += 1}", id: "blah", type: "text", name: "blah",  }
+
+## Plugins ##
+
+I've written a couple of plugins. If you wish to write one yourself you'll need to look for the code for now until I write some proper instructions.
+
+To load a plugin called "Aria":
+
+    Campo.plugin :Aria
+
+### Aria ###
+
+Helpful methods for outputting forms that add in the [WAI-ARIA](http://www.w3.org/WAI/intro/aria) attributes into your forms.
+
+Here's an example of how I've used this with an account registration form to provide information about each field:
+
+    require 'campo'
+
+    Campo.plugin :Aria
+
+    div = Campo.literal "#session.form" do
+      self << Campo.form( "register" ) do
+        fieldset "Register" do
+          literal "%p.warning" do
+            literal "Fields marked with an <em>*</em> are required."
+          end
+          text( "email_address", size: 40 ).describe("A valid email address, please.", class: "validation info description")
+          text( "username", size: 40 ).describe([["Must be 3 characters at least.", {class: 'validate_username required', id: 'username_length'}], ["No spaces or punctuation, only numbers, letters and underscores, please.", {class: 'validate_username required', id: 'username_specialchars'}], ["You may not use your email address as a username.", {class: 'validate_username required', id: 'username_not_email_address'}]], class: "validation info description")
+          password( "password", size: 40 ).describe([["Must be 8 characters at least.",{class: 'validate_password required', id: 'password_length'}],["It's better to add some numbers/punctuation.", class: 'validate_password', id: 'password_specialchars'],["You may not use your email address or username as a password.", {class: 'validate_password required', id: 'password_not_email_address'}],["For strength, try to make it a phrase, and not to be something you've previously used.",{}]], class: "validation info description")
+          bit_of_ruby "= Rack::Csrf.tag(env)"
+          literal "#validation_overall_result.validation.hidden" do
+            literal "There were problems with the form entries. Please check the highlighted fields."
+          end
+          submit
+        end
+      end
+    end
+    
+    
+    
+    puts Campo.output div
+
+Now let's take a look at the output of the email_address field:
+
+    %label{ for: "email_address",  }
+      Email address
+      %span{id: "email_address_description", class: "validation info description", }
+        A valid email address, please.
+      %input{ atts[:email_address], tabindex: "#{@campo_tabindex += 1}", id: "email_address", type: "text", size: "40", name: "email_address", :"aria-describedby" => "email_address_description",  }
+      
+Notice how the label contains a span that precedes the input field - this is helpful for screen readers because those that aren't using ARIA will still hit the description. The input field refers to this span using the aria-describedby attribute.
+
+For a more complex example, look at the output for username:
+
+    %label{ for: "username",  }
+      Username
+      %span{id: "username_description", class: "validation info description", }
+        %ul
+          %li{ id: "username_length", class: "validate_username required", }
+            Must be 3 characters at least.
+          %li{ id: "username_specialchars", class: "validate_username required", }
+            No spaces or punctuation, only numbers, letters and underscores, please.
+          %li{ id: "username_not_email_address", class: "validate_username required", }
+            You may not use your email address as a username.
+      %input{ atts[:username], tabindex: "#{@campo_tabindex += 1}", id: "username", type: "text", size: "40", name: "username", :"aria-describedby" => "username_description",  }
+
+For the campo code, we added an array of tuples to the `describe` method. These tuples are then made into an unordered list within the span. The first part of each tuple is the text description, the second part any attributes you with the list item to have. I've used this in a project in conjunction with JQuery to produce dynamic information back to the user of the form. You don't have to pass the second part of the tuple, in other words you can do:
+
+    text("d").describe([["You"], ["Me"], ["Them"]])
+
+But I would usually expect that you'd want to pass each item an id. It's up to you.
+
+### Contributing ###
+
+When contributings, most of all, remember that **any** contribution you can make will be valuable, whether that is putting in a ticket for a feature request (or a bug, but they don't happen here;), cleaning up some grammar, writing some documentation (or even a blog post, let me know!) or a full blooded piece of code - it's **all** welcome and encouraged.
+
+To contribute some code:
+
+1. Fork this, then:
+* `git clone git@github.com:YOUR-USERNAME/Campo.git`
+* `git remote add upstream git@github.com:yb66/Campo.git`
+* `git fetch upstream`
+* `git checkout develop`
+* Decide on the feature you wish to add.  
+    - Give it a snazzy name, such as **kitchen_sink**.  
+    - `git checkout -b kitchen_sink`
+* Install Bundler.  
+    - `gem install bundler -r --no-ri --no-rdoc`
+* Install gems from Gemfile.  
+    - `bundle install --binstubs --path vendor`  
+    - Any further updates needed, just run `bundle install`, it'll remember the rest.
+* Write some specs.
+* Write some code. (Yes, I believe that is the correct order, and you'll never find me doing any different;)
+* Write some documentation using Yard comments - see [Yard's Getting Started](http://rubydoc.info/docs/yard/file/docs/GettingStarted.md)  
+  - Use real English (i.e. full stops and commas, no l33t or LOLZ). I'll accept American English even though it's ugly. Don't be surprised if I 'correct' it.  
+  - Code without comments won't get in, I don't have the time to work out what you've done if you're not prepared to spend some time telling me (and everyone else).
+* Run `reek PATH_TO_FILE_WITH_YOUR_CHANGES` and see if it gives you any good advice. You don't have to do what it says, just consider it.
+* Run specs to make sure you've not broken anything. If it doesn't pass all the specs it doesn't get in.  
+  - Have a look at coverage/index.htm and see if all your code was checked. We're trying for 100% code coverage.
+* Run `bin/rake docs` to generate documentation.  
+    - Open up docs/index.html and check your documentation has been added and is clear.
+* Add a short summary of your changes to the CHANGES file. Add your name and a link to your bio/website if you like too.
+* Send me a pull request.  
+    - Don't merge into the develop branch!  
+    - Don't merge into the master branch!  
+    - see [http://nvie.com/posts/a-successful-git-branching-model/](http://nvie.com/posts/a-successful-git-branching-model/) for more on how this is supposed to work.
+* Wait for worldwide fame.
+* Shrug and get on with your life when it doesn't arrive, but know you helped quite a few people in their life, even in a small way - 1000 raindrops will fill a bucket!
+
+
 ## Licence ##
 
 This is under the MIT Licence.
 
-Copyright (c) 2011 Iain Barnett
+Copyright (c) 2012 Iain Barnett
 
 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: