message_block 1.0

data/CHANGELOG.rdoc

@@ -0,0 +1,9 @@
+== [2010-10-13] 1.0 Major Updates
+
+* Finally updated to be a Gem
+* Internal refactoring
+* Converted tests to RSpec
+* New cucumber features
+* Added support for Rails 3.0
+
+== 0.1.0 Initial Beta Version

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Ben Hughes
+
+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.rdoc

@@ -0,0 +1,126 @@
+== Message Block
+
+Implements the common view pattern by which a list of messages are shown at the top, 
+often a combination of flash messages and ActiveRecord validation issues on one or more models.  
+This allows for a nice, stylized block of messages at the top of the page with icons 
+indicating what type of message it is (error, confirmation, warning, etc.)
+
+This view helper acts as a replacement for error_messages_for by taking error messages 
+from your models and combing them with flash messages (multiple types such as error, confirm, etc.) 
+and outputting them to your view.  This plugin comes with an example stylesheet and images.
+
+== Installation
+
+Include the gem using bundler in your Gemfile:
+
+  gem "message_block"
+
+Then run the rake task to install the static files:
+  
+  rake message_block:install
+
+== Usage
+
+Once you install this, you should now have a set of images at public/images/message_block and 
+a basic stylesheet installed at public/stylesheets/message_block.css.  First you'll want to either 
+reference this in your layout or copy the declarations to your main layout.  Then you can use 
+the helper <tt><%= message_block %></tt> as described below:
+
+The first argument specifies a hash options:
+
+* <tt>:on</tt> - specifies one or many model names for which to check error messages.
+* <tt>:model_error_type</tt> - specifies the message type to use for validation errors; defaults to 'error'
+* <tt>:flash_types</tt> - specifies the keys to check in the flash hash.  Messages will be grouped in ul 
+  lists according to this type.  Defaults to: %w(back confirm error info warn)
+* <tt>:html</tt> - Specifies HTML options for the containing div
+* <tt>:id</tt> - Specifies ID of the containing div; defaults to 'message_block'
+* <tt>:class</tt> - Specifies class name of the containing div; defaults to nothing.
+* <tt>:container</tt> - specifies which block-level element to contain the errors (defaults to :div).
+
+=== Example
+Imagine you have a form for entering a user and a comment:
+
+  <%= message_block :on => [:user, :comment] %>
+
+Imagine also you set these flash variables in the controller:
+  class CommentsController
+    def create
+      flash.now[:error] = "Error A"
+      flash.now[:confirm] = "Confirmation A"  # Note you can use different types
+      flash.now[:warn] = ["Warn A", "Warn B"]  # Can set to an array for multiple messages
+    end
+  end
+
+And let's say that you want to show these messages but also show the validation issues 
+given that both user and comment fail ActiveRecord validation:
+
+  <div id="message_block" class="message_block">
+    <ul class="error">
+      <li>Error A</li>
+      <li>User first name is required.</li>
+      <li>Comment contents is required.</li>
+    </ul>
+    <ul class="confirm">
+      <li>Confirmation A</li>
+    </ul>
+    <ul class="warn">
+      <li>Warn A</li>
+      <li>Warn B</li>
+    </ul>
+  </div>
+
+=== Ajax & JavaScript Integration
+
+Sometimes you'll want to use the message block pattern within JavaScript.  Wouldn't it be nice to just populate 
+the message_block DOM tree based on a JavaScript object not unlike Rails flash?
+
+Included in the plugin is a Prototype JS implementation to make this easier.  Note that this file is *not* automatically 
+copied when the plugin is installed.  Currently only a Prototype version is available (jQuery coming soon!)
+  
+  assets/javascripts/message_block_prototype.js
+
+Example Usage:
+  
+  <div id="something">
+    <%= message_block :on => :job %>
+  </div>
+  
+  <script type="text/javascript">
+    document.observe('dom:loaded', function() {
+      message_block = new MessageBlock('message_block');  // Default ID is message_block, being explicit
+      
+      // Updates with two errors and one confirmation
+      message_block.update({
+        error: ['Error One', 'Error Two'],
+        confirm: ['Confirmation Message']
+      });
+      
+      // Clears the message block
+      message_block.clear();
+      
+      // Same as above...
+      message_block.update({});
+    });
+  </script>
+
+This could be useful if you're interacting with stuff via Ajax, for example:
+
+  # In Controller
+  wants.json do
+    render :status => :unprocessable_entity, :json => { 'error' => @job.errors.full_messages }
+  end
+  
+  # JavaScript Ajax
+  new Ajax.Request("/jobs", {
+    method: 'get',
+    
+    onFailure: function(transport) {
+      this.message_block.update(transport.responseJSON);
+    },
+    
+    onSuccess: function(transport) {
+      this.message_block.clear();
+      
+      // Do something...
+    }
+  });

data/Rakefile

@@ -0,0 +1,23 @@
+require 'rubygems'
+require 'rake'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+
+desc "Run specs"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = Rake::FileList["spec/**/*_spec.rb"]
+  t.spec_opts = ["-c"]
+end
+
+task :default => :spec
+
+desc "Generate documentation for the plugin."
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.title    = "message_block"
+  rdoc.options << "--line-numbers" << "--inline-source"
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Dir["#{File.dirname(__FILE__)}/lib/tasks/*.rake"].sort.each { |ext| load ext }

data/init.rb

@@ -0,0 +1 @@
+require "message_block"

data/lib/message_block/helpers.rb

@@ -0,0 +1,54 @@
+module MessageBlock
+  module Helpers
+    
+    def message_block(options = {})
+      options.assert_valid_keys(:on, :model_error_type, :flash_types, :html, :id, :class, :container)
+      
+      options[:model_error_type] ||= :error
+      options[:flash_types] ||= [:notice, :back, :confirm, :error, :info, :warn].sort_by(&:to_s)
+      options[:on] ||= controller.controller_name.split('/').last.gsub(/\_controller$/, '').singularize.to_sym
+      options[:html] ||= {:id => "message_block", :class => "message_block"}
+      options[:html][:id] = options[:id] if options[:id]
+      options[:html][:class] = options[:class] if options[:class]
+      options[:container] = :div if options[:container].nil?
+      
+      flash_messages = {}
+      
+      options[:flash_types].each do |type|
+        entries = flash[type.to_sym]
+        next if entries.nil?
+        entries = [entries] unless entries.is_a?(Array)
+        
+        flash_messages[type.to_sym] ||= []
+        flash_messages[type.to_sym] += entries
+      end
+      
+      options[:on] = [options[:on]] unless options[:on].is_a?(Array)
+      
+      options[:on] = [options[:on]] unless options[:on].is_a?(Array)
+      model_objects = options[:on].map do |model_object|
+        if model_object.instance_of?(String) or model_object.instance_of?(Symbol)
+          instance_variable_get("@#{model_object}")
+        else
+          model_object
+        end
+      end.select {|m| !m.nil? }
+      
+      model_errors = model_objects.inject([]) {|b, m| b += m.errors.full_messages }
+      
+      flash_messages[options[:model_error_type].to_sym] ||= []
+      flash_messages[options[:model_error_type].to_sym] += model_errors
+      
+      contents = flash_messages.keys.sort_by(&:to_s).select {|type| !flash_messages[type.to_sym].empty? }.map do |type|
+        "<ul class=\"#{type}\">" + flash_messages[type.to_sym].map {|message| "<li>#{message}</li>" }.join + "</ul>"
+      end.join
+      
+      if options[:container]
+        content_tag(options[:container], contents, options[:html], false)
+      else
+        contents
+      end
+    end
+    
+  end
+end

data/lib/message_block/railtie.rb

@@ -0,0 +1,21 @@
+module MessageBlock
+  if defined?(Rails::Railtie)
+    class Railtie < Rails::Railtie
+      initializer "message_block.insert_helpers" do
+        ActiveSupport.on_load(:action_view) do
+          MessageBlock::Railtie.insert
+        end
+      end
+      
+      rake_tasks do
+        load "tasks/message_block.rake"
+      end
+    end
+  end
+  
+  class Railtie
+    def self.insert
+      ActionView::Base.send(:include, MessageBlock::Helpers)
+    end
+  end
+end

data/lib/message_block.rb

@@ -0,0 +1,4 @@
+require "rubygems"
+require "active_support"
+require "message_block/helpers"
+require "message_block/railtie"

data/lib/tasks/message_block.rake

@@ -0,0 +1,36 @@
+namespace :message_block do
+  desc "Installs static files for the message_block gem"
+  task :install do
+    puts "Copying assets..."
+    
+    images_source = File.join(File.dirname(__FILE__), "..", "..", "assets", "images")
+    stylesheets_source = File.join(File.dirname(__FILE__), "..", "..", "assets", "stylesheets", "message_block.css")
+    javascripts_source = File.join(File.dirname(__FILE__), "..", "..", "assets", "javascripts", "message_block.js")
+    
+    images_target = Rails.root.join("public", "images", "message_block")
+    stylesheets_target = Rails.root.join("public", "stylesheets", "message_block.css")
+    javascripts_target = Rails.root.join("public", "javascripts", "message_block.js")
+    
+    unless File.exists?(images_target)
+      FileUtils.cp_r(images_source, images_target)
+      puts "  Copied Images"
+    else
+      puts "  Images appear to already be installed, not copying."
+    end
+    
+    unless File.exists?(stylesheets_target)
+      FileUtils.cp(stylesheets_source, stylesheets_target)
+      puts "  Copied Stylesheet"
+    else
+      puts "  Stylesheet appears to already be installed, not copying"
+    end
+    
+    unless File.exists?(javascripts_target)
+      FileUtils.cp(javascripts_source, javascripts_target)
+      puts "  Copied Javascript"
+    else
+      puts "  Javascript appears to already be installed, not copying"
+    end
+    
+  end
+end

data/spec/message_block/helpers_spec.rb

@@ -0,0 +1,124 @@
+require "spec_helper"
+
+describe MessageBlock::Helpers do
+  include ActionView::Helpers::TagHelper
+  include MessageBlock::Helpers
+  
+  before do
+    setup_post
+    setup_user
+  end
+  
+  it "should not accept invalid options" do
+    lambda { message_block :invalid => "option" }.should raise_error(ArgumentError)
+  end
+  
+  it "should accept valid options" do
+    lambda {
+      message_block :on => :post, 
+        :model_error_type => "fail",
+        :flash_types => %w(error warn),
+        :html => {:style => 'height: 10em'},
+        :id => "block",
+        :class => "messages"
+    }.should_not raise_error
+  end
+  
+  it "should show nothing with no errors" do
+    message_block.should == %(<div class="message_block" id="message_block"></div>)
+  end
+  
+  it "should automatically find post errorts with posts controller" do
+    @controller = posts_controller
+    output = message_block
+    output.should == %(<div class="message_block" id="message_block"><ul class="error"><li>Author name can't be empty</li></ul></div>)
+  end
+  
+  it "should give no error for post" do
+    output = message_block(:on => :post)
+    output.should == %(<div class="message_block" id="message_block"><ul class="error"><li>Author name can't be empty</li></ul></div>)
+  end
+  
+  it "should give error for user" do
+    output = message_block(:on => :user)
+    output.should == %(<div class="message_block" id="message_block"><ul class="error"><li>User email can't be empty</li></ul></div>)
+  end
+  
+  it "should give errors for both post and user" do
+    output = message_block(:on => [:post, :user])
+    output.should == %(<div class="message_block" id="message_block"><ul class="error"><li>Author name can't be empty</li><li>User email can't be empty</li></ul></div>)
+  end
+  
+  it "should give errors for both post and user in the correct order" do
+    output = message_block(:on => [:user, :post])
+    output.should == %(<div class="message_block" id="message_block"><ul class="error"><li>User email can't be empty</li><li>Author name can't be empty</li></ul></div>)
+  end
+  
+  it "should give error for user given direct instance variable" do
+    output = message_block(:on => @user)
+    output.should == %(<div class="message_block" id="message_block"><ul class="error"><li>User email can't be empty</li></ul></div>)
+  end
+  
+  it "should respect model error type" do
+    output = message_block(:on => :user, :model_error_type => "fail")
+    output.should == %(<div class="message_block" id="message_block"><ul class="fail"><li>User email can't be empty</li></ul></div>)
+  end
+  
+  it "should be able to specify id for containing div" do
+    output = message_block(:id => "messages")
+    output.should == %(<div class="message_block" id="messages"></div>)
+  end
+  
+  it "should be able to specify class for containing div" do
+    output = message_block(:class => "messages")
+    output.should == %(<div class="messages" id="message_block"></div>)
+  end
+  
+  it "should be able to specify html options for containing div" do
+    output = message_block(:html => {:id => "block", :class => "messages"})
+    output.should == %(<div class="messages" id="block"></div>)
+  end
+  
+  it "should be able to specify container option as false" do
+    output = message_block(:on => :post, :container => false)
+    output.should == %(<ul class="error"><li>Author name can't be empty</li></ul>)
+  end
+  
+  it "should be able to specify container option" do
+    output = message_block(:on => :post, :container => :fieldset)
+    output.should == %(<fieldset class="message_block" id="message_block"><ul class="error"><li>Author name can't be empty</li></ul></fieldset>)
+  end
+  
+  it "should be able to see flash error string" do
+    flash[:error] = "Error A"
+    output = message_block
+    output.should == %(<div class="message_block" id="message_block"><ul class="error"><li>Error A</li></ul></div>)
+  end
+  
+  it "should be able to see flash error array" do
+    flash[:error] = ["Error A", "Error B"]
+    output = message_block
+    output.should == %(<div class="message_block" id="message_block"><ul class="error"><li>Error A</li><li>Error B</li></ul></div>)
+  end
+  
+  it "should be able to see default flash types" do
+    default_types = [:notice, :back, :confirm, :error, :info, :warn].sort_by(&:to_s)
+    default_types.each do |type|
+      flash[type] = type.to_s
+    end
+    
+    expected_contents = default_types.map do |type|
+      content_tag(:ul, content_tag(:li, type.to_s), :class => type.to_s)
+    end.join
+    
+    output = message_block
+    output.should == %(<div class="message_block" id="message_block">#{expected_contents}</div>)
+  end
+  
+  it "should be able to see flash error alongside model error" do
+    flash[:error] = "Error A"
+    output = message_block(:on => :post)
+    output.should == %(<div class="message_block" id="message_block"><ul class="error"><li>Error A</li><li>Author name can't be empty</li></ul></div>)
+  end
+  
+end

data/spec/spec.opts

@@ -0,0 +1,5 @@
+--colour
+--format nested
+--loadby mtime
+--reverse
+--backtrace

data/spec/spec_helper.rb

@@ -0,0 +1,74 @@
+require "rubygems"
+require "spec"
+require "active_support"
+require "action_view"
+require "message_block"
+
+require File.dirname(__FILE__) + '/../init'
+
+Spec::Runner.configure do |config|
+  config.mock_with :mocha
+end
+
+# Borrowed model stubs from Rails active_record_helper_test.rb
+# TODO: Re-implement using mocha
+Post = Struct.new("Post", :title, :author_name)
+User = Struct.new("User", :email)
+
+def setup_post
+  @post = Post.new
+  def @post.errors
+    Class.new do
+      def on(field)
+        case field.to_s
+        when "author_name"
+          "can't be empty"
+        when "body"
+          true
+        else
+          false
+        end
+      end
+      def empty?() false end
+      def count() 1 end
+      def full_messages() [ "Author name can't be empty" ] end
+    end.new
+  end
+  
+  @post.title       = "Hello World"
+  @post.author_name = ""
+end
+
+def setup_user
+  @user = User.new
+  def @user.errors
+    Class.new {
+      def on(field) field == "email" end
+      def empty?() false end
+      def count() 1 end
+      def full_messages() [ "User email can't be empty" ] end
+    }.new
+  end
+  
+  @user.email = ""
+end
+
+def controller
+  @controller ||= Class.new {
+    def controller_name
+      "widgets_controller"
+    end
+  }.new
+end
+
+def posts_controller
+  Class.new {
+    def controller_name
+      "posts_controller"
+    end
+  }.new
+end
+
+def flash
+  @flash ||= {}
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification 
+name: message_block
+version: !ruby/object:Gem::Version 
+  hash: 15
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  version: "1.0"
+platform: ruby
+authors: 
+- Ben Hughes
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-10-14 00:00:00 +08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 5
+        segments: 
+        - 2
+        - 2
+        - 1
+        version: 2.2.1
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: actionpack
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 5
+        segments: 
+        - 2
+        - 2
+        - 1
+        version: 2.2.1
+  type: :runtime
+  version_requirements: *id002
+description: Implements the common view pattern by which a list of messages are shown at the top, often a combination of flash messages and ActiveRecord validation issues on one or more models.
+email: ben@railsgarden.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/message_block/helpers.rb
+- lib/message_block/railtie.rb
+- lib/message_block.rb
+- lib/tasks/message_block.rake
+- spec/message_block/helpers_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+- CHANGELOG.rdoc
+- LICENSE
+- Rakefile
+- README.rdoc
+- init.rb
+has_rdoc: true
+homepage: http://github.com/rubiety/message_block
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 19
+      segments: 
+      - 1
+      - 3
+      - 4
+      version: 1.3.4
+requirements: []
+
+rubyforge_project: message_block
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Flash message and error_messages_for handling with a common interface.
+test_files: []
+