instructions 0.1.0

data/.gitignore

@@ -0,0 +1,9 @@
+.DS_Store
+.rvmrc
+.rspec
+coverage
+rdoc
+doc
+.yardoc
+.bundle
+pkg

data/Gemfile

@@ -0,0 +1,7 @@
+source "http://rubygems.org"
+
+group :development do
+  gem "rspec", "~> 2.1.0"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.2"
+end

data/Gemfile.lock

@@ -0,0 +1,26 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.2)
+    git (1.2.5)
+    jeweler (1.5.2)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    rake (0.8.7)
+    rspec (2.1.0)
+      rspec-core (~> 2.1.0)
+      rspec-expectations (~> 2.1.0)
+      rspec-mocks (~> 2.1.0)
+    rspec-core (2.1.0)
+    rspec-expectations (2.1.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.1.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0.0)
+  jeweler (~> 1.5.2)
+  rspec (~> 2.1.0)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Scott Bellware
+
+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:
+
+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/README.textile

@@ -0,0 +1,141 @@
+h1. Instructions Plugin for Rails 3
+
+h2. Introduction
+
+Instructions is a form builder plugin for Ruby on Rails 3 that displays model errors and hints for form fields next to those fields.
+
+The plugin renders instructions for fields when the fields don't have errors, and renders model errors for fields when they do have errors.
+
+It wraps labels for fields with errors in a div that has a unique HTML ID and class names that provide easy control over styling, as well as selecting elements for web testing frameworks like Selenium and context-scraping tools.
+
+A field with many error messages is represented as a comma-separated list.  For Example: @Name can't be blank, is not a number@
+
+The rendering of the field and the hints and error messages can be piped through procs for further formatting. These procs can be configured globally, as well as specified directly in markup on a field-by-field basis. Global configuration is done with a Rails initializer.
+
+h2. How it Plugs in to Rails
+
+During initialization, the plugin replaces the @ActionView::Base.field_error_proc@ with the plugin's code (found in @field_error.rb@) and mixes in the @instructions@ helper into the existing FormHelper. See @lib/instructions/core_ext/action_view.ext@ for details.
+
+h2. Installation
+
+The Instructions plugin is a Ruby Gem hosted at rubygems.org.
+
+Install the gem using:
+
+@gem install instructions@
+
+h3. Configurable Formatting of Field Names, Error Messages, and Instructions
+
+Field names and instructions and error message formatting can be controlled and customized using configurable interceptors.
+
+There are three contexts where the plugin can produce different results. In all three cases, these results are configurable using Proc objects that can provided using a Rails initializer:
+
+|*Symbol*|*Conditions*|
+|:new|The initial rendering of a new action when a field's hint is rendered|
+|:valid|The rendering for an attribute that has no validation errors after a post|
+|:invalid|The rendering for an attribute that does have validation errors after a post|
+
+In each case, the attribute name formatting and the instructions formatting can be intercepted and replaced.
+
+The following code is an example of a Rails initializer (in the @config/initializers@ directory of your rails app).
+
+NOTE: The filename of the initializer is @instructions.rb@, but the filename isn't significant. As long as the initializer is in the initializer directory.
+
+bc.. upcase_proc = Proc.new { |text| text.upcase }
+downcase_proc = Proc.new { |text| text.downcase }
+empty_proc = Proc.new { "" }
+
+Instructions.configure do |config|
+  config.format_attribute_name :new, &downcase_proc
+  config.format_instructions :new, &downcase_proc
+  
+  config.format_attribute_name :valid, &downcase_proc
+  config.format_instructions :valid, &empty_proc
+  
+  config.format_attribute_name :invalid, &downcase_proc
+  config.format_instructions :invalid, &downcase_proc
+  
+  config.message_joiner { |messages| messages.join ', ' }
+end
+
+p. Note also that you can configure a proc that controls how a list of messages are joined.
+
+p. The configuration code above:
+* Converts the attribute name and the instructions to lower case during the initial get of an input form for a "new" action
+* Converts the attribute name to lower case when rendering the instructions for a field for an attribute that has a value and has no validation errors. The instructions, in this case, are not rendered at all as they are replaced with an empty string.
+* Converts the attribute name and error message to lower case when rendering the instructions for a field for an attribute that has a value and has validation errors. 
+* Joins all error messages using a comma followed by a space.
+
+h3. A Note on Attribute Name Formatting
+
+Attribute names are humanized using @model.class.human_attribute_name(attribute_name)@ before being passed to the tag helpers.
+
+h2. Example
+
+The example demonstrates the use of Field Instructions with a label and a textbox. The example model is a @Person@ and the model attribute is @Name@.
+
+The name attribute has a @validates_presence_of@ constraint.
+
+The ERB code for the label, text box, and instructions helper is:
+
+bc.. <%= form.label(:name, "Name") %>
+<%= form.text_field(:name) %>
+<%= form.instructions(:name, "can't be blank") %>
+
+p. The HTML rendering for this is:
+
+bc.. <label for="project_name">Name</label>
+<input id="project_name" name="project[name]" size="30" type="text" />
+<div id="project_name_instructions" data-for="project_name" class="instructions">name can't be blank</div>
+
+p. When the project_name input is posted with a blank value, the instructions div is replaced with an error message div that contains any model errors for the project.name attribute:
+
+@<div id="project_name_error_message" data-for="project_name" class="instructions invalid">name can't be blank</div>@
+
+h3. Example App
+
+See "https://github.com/sbellware/instructions-example":https://github.com/sbellware/instructions-example for a (very) basic example of a Rails 3 app with Instructions.
+
+h2. Using Symbols and i18n Errors to Render Hints
+
+The instructions helper can be invoked with a symbol (eg: @:blank@) rather than passing instructions as text. This will use the error messages defined in Rails' i18n as hints. In order to use this, the default error message strings have to be changed to allow them to be used both as hints and as error messages.
+
+See @extras/hint_errors.en.yml@ for examples. This file can be copied into your application's @config/locals@ if you prefer to use this technique.
+
+h3. Some Examples
+
+Render the i18n @:blank@ error message as a hint:
+
+<%= form.instructions(:name, :blank) %>
+
+Render the i18n @:blank@ and @:too_short@ error messages as a hint:
+
+<%= form.instructions(:name, [:blank, {:too_short => 2}]) %>
+
+Note that in the above example, the minimum length of the field must be specified since the @:too_short@ string requires an interpolation argument to be provided. The definition of the @:too_short@ string is @hint_errors.en.yml@ is:
+
+@too_long: "can't be more than %{count} characters"@
+
+h2. Rails Defaults Changed by the Plugin
+
+The _default_ rails rendering of the HTML when the form is posted with a blank value in the name textbox is:
+
+bc.. <div class="field_with_errors"><label for="project_name">Name</label></div>
+<div class="field_with_errors"><input id="project_name" name="project[name]" size="30" type="text" value="" /></div>
+
+p. Using the Instructions plugin, the rendering of the HTML when the form is posted with a blank value in the name textbox is:
+
+bc.. <div class="field_with_errors_label"><label for="project_name">Name</label></div>
+<div class="field_with_errors"><input id="project_name" name="thing[name]" size="30" type="text" value=""></div>
+<div id="project_name_error_message" data-for="project_name" class="instructions invalid">name can't be blank</div>
+
+h2. CSS Classes and HTML Markup
+
+|*Name*|*Attribute Type*|*Notes*|
+|instructions|Class|Applied to the div that contains the instructions|
+|valid|Class|Applied to the div that contains the instructions for fields with valid data after the form is posted. This class is always rendered together with the "instructions" class. The order of precedence of the class renderings is @instructions@ first, followed by @valid@ second, allowing styling for valid instructions to override the general instructions styling. The HTML rendering for the class attribute for the span is: @class="instructions valid"@|
+|invalid|Class|Applied to the div that contains error messages after the form is posted|
+|{model}_{attribute}_instructions|Id|A unique ID applied to the div that contains the instructions for the field, where @{model}@ is the name of the ActiveModel object and @{attribute}@ is the name of the attribute that has the error. Example: @project_name_instructions@|
+|{model}_{attribute}_error_message|Id|A unique ID applied to the div that contains the error messages for the field, where @{model}@ is the name of the ActiveModel object and @{attribute}@ is the name of the attribute that has the error. Example: @project_name_error_message@|
+|field_with_errors|Class|Applied to a div that wraps the HTML element that represents the model field that has errors.|
+|field_with_errors_label|Class|Applied to a div that wraps any HTML label for the field with errors.|

data/Rakefile

@@ -0,0 +1,40 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new
+task 'gemspec:generate' do
+	puts "NOTE: The gemspec is not generated by Jeweler. It's maintained in instructions.gemspec."
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = false
+end
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "instructions #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/extras/hint_errors.en.yml

@@ -0,0 +1,27 @@
+en:
+  errors:
+    # The default format to use in full error messages.
+    format: "%{attribute} %{message}"
+
+    # The values :model, :attribute and :value are always available for interpolation
+    # The value :count is available when applicable. Can be used for pluralization.
+    messages:
+      inclusion: "must be included in the list"
+      exclusion: "must not be reserved"
+      invalid: "can't be invalid"
+      confirmation: "must match the confirmation"
+      accepted: "must be accepted"
+      empty: "can't be empty"
+      blank: "can't be blank"
+      too_long: "can't be more than %{count} characters"
+      too_short: "can't be less than %{count} characters"
+      wrong_length: "must be %{count} characters"
+      not_a_number: "must be a number"
+      not_an_integer: "must be an integer"
+      greater_than: "must be greater than %{count}"
+      greater_than_or_equal_to: "must be greater than or equal to %{count}"
+      equal_to: "must be equal to %{count}"
+      less_than: "must be less than %{count}"
+      less_than_or_equal_to: "must be less than or equal to %{count}"
+      odd: "must be odd"
+      even: "must be even"

data/install.rb

@@ -0,0 +1 @@
+# Install hook code here

data/instructions.gemspec

@@ -0,0 +1,19 @@
+Gem::Specification.new do |s|
+  s.rubygems_version = %q{1.3.7}
+
+  s.name = %q{instructions}
+  s.description = %q{Rails 3 plugin that renders error messages and input hints next to their fields with semantic markup}
+  s.summary = %q{Semantic Error Message and Hint Markup for Rails 3 Form Fields}
+  s.version = "0.1.0"
+  s.date = %q{2011-01-24}
+  s.authors = ["Scott Bellware"]
+  s.email = %q{opensource@ampgt.com}
+  s.homepage = %q{http://github.com/sbellware/instructions}
+  s.licenses = ["MIT"]
+
+  s.files = `git ls-files`.split("\n")
+	s.test_files = `git ls-files -- {spec}/*`.split("\n")
+
+  s.require_path = "lib"
+end
+

data/instructions.gemspec.generated

@@ -0,0 +1,89 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{instructions}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Scott Bellware"]
+  s.date = %q{2011-01-24}
+  s.description = %q{Rails 3 plugin that renders error messages and input hints next to their fields with semantic markup}
+  s.email = %q{opensource@ampgt.com}
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.textile"
+  ]
+  s.files = [
+    ".gitignore",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.textile",
+    "Rakefile",
+    "VERSION",
+    "extras/hint_errors.en.yml",
+    "init.rb",
+    "install.rb",
+    "instructions.gemspec",
+    "lib/core_files.rb",
+    "lib/instructions.rb",
+    "lib/instructions/abstract.rb",
+    "lib/instructions/attribute_state.rb",
+    "lib/instructions/configuration.rb",
+    "lib/instructions/core_ext/action_view_ext.rb",
+    "lib/instructions/error_message.rb",
+    "lib/instructions/error_message_tag.rb",
+    "lib/instructions/field_error.rb",
+    "lib/instructions/field_instructions.rb",
+    "lib/instructions/form_helper.rb",
+    "lib/instructions/formatters.rb",
+    "lib/instructions/instructions_tag.rb",
+    "lib/instructions/tag.rb",
+    "lib/instructions/valid_instructions_tag.rb",
+    "rails/init.rb",
+    "spec/attribute_state_spec.rb",
+    "spec/configuration_spec.rb",
+    "spec/error_message_spec.rb",
+    "spec/error_message_tag_spec.rb",
+    "spec/fake_model.rb",
+    "spec/field_error_spec.rb",
+    "spec/form_helper_spec.rb",
+    "spec/formatters_spec.rb",
+    "spec/spec_helper.rb",
+    "spec/support/field_instructions_namespace.rb",
+    "spec/support/html_safe_string.rb",
+    "spec/support/rspec_patches.rb",
+    "spec/tag_spec.rb",
+    "test/instructions_test.rb",
+    "test/test_helper.rb",
+    "uninstall.rb"
+  ]
+  s.homepage = %q{http://github.com/sbellware/instructions}
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Semantic Error Message and Hint Markup for Rails 3 Form Fields}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, ["~> 2.1.0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.5.2"])
+    else
+      s.add_dependency(%q<rspec>, ["~> 2.1.0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+    end
+  else
+    s.add_dependency(%q<rspec>, ["~> 2.1.0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+  end
+end
+

data/lib/core_files.rb

@@ -0,0 +1,4 @@
+core_files = Dir[File.join(File.expand_path(File.dirname(__FILE__)), 'instructions', '*.rb')]
+core_files.each do |file|
+	require file.gsub(/.rb/, '')
+end

data/lib/instructions.rb

@@ -0,0 +1,6 @@
+require File.join(File.expand_path(File.dirname(__FILE__)), 'core_files')
+
+core_ext_files = Dir[File.join(File.expand_path(File.dirname(__FILE__)), '..', 'lib', 'instructions', 'core_ext', '*.rb')]
+core_ext_files.each do |file|
+	require file.gsub(/.rb/, '')
+end

data/lib/instructions/abstract.rb

@@ -0,0 +1,21 @@
+# see: http://stackoverflow.com/questions/512466/how-to-implement-an-abstract-class-in-ruby
+
+module Instructions
+	module Abstract
+	  def self.included(base)
+	    base.extend(ClassMethods)
+	  end
+
+	  module ClassMethods
+	    def abstract_method(*args)
+	      args.each do |name|
+	        class_eval(<<-END, __FILE__, __LINE__)
+	          def #{name}(*args)
+	            raise NotImplementedError.new("#{self}\##{name} is abstract.")
+	          end
+	        END
+	      end
+	    end
+	  end
+	end
+end

data/lib/instructions/attribute_state.rb

@@ -0,0 +1,25 @@
+module Instructions
+	module AttributeState
+		def determine(method)
+			return :new if initial_get_of_new_form? method
+			return :valid if valid_attribute? method
+			return :invalid if not valid_attribute? method
+		end
+
+		def initial_get_of_new_form?(method)
+			@object.new_record? and blank_valid_attribute? method
+		end
+
+		def blank_valid_attribute?(method)
+			 valid_attribute? method and blank_attribute? method 
+		end
+
+		def valid_attribute?(method)
+			@object.errors[method].empty?
+		end
+
+		def blank_attribute?(method)
+			@object.send(method).nil?
+		end
+	end
+end