=========================================================
DISCLAIMER:  Note this is a work in progress!
We're letting it be open on github in hopes that it'll be
useful to someone and we'll get some good ideas back.
However, all bets are off when it comes to stability of
the API and functionality.  

(For example, I know I'm putting too much code in the view 
right now, and I'm working on drastically changing that 
in the next iteration.)

Thanks! -- Larry 2008-09-05
=========================================================

WickedMessenger
==================

== Good Error Messages For Developers ==
I want to be able to have as many validations in my model as I want.  I want those validations 
to have technical, precise, even pedantic error messages.  This is especially helpful when using 
an XML web service API.  These types of "computer-ish" error messages, however, are not good 
for end-users.

== Bad Error Messages for End-Users ==
Why are Rails validation errors not good for end-users?  Well, error messages need to be aware 
of the context they're in, use plain English, and suggest a way for the user to repair the 
situation.  Since the model is blissfully unaware of the view the user is looking at way, way up 
in the app stack, how can the model ever hope to fill all those requirements?  It really can't, 
and even if it did, you'd be leaking your view into your model.  This sucks.

Example
=======

Say you're building a Company object, but one of the fields is an "Administrator Email" that 
will actually create a component User object.  The error messages, if you leave the email 
address blank, would look something like this:

------------------------------------------------------------------
3 errors prohibited this from being saved
There were problems with the following fields:

    * Invitee is invalid
    * Email can't be blank
    * Email is too short (minimum is 3 characters)
------------------------------------------------------------------

What does this mean to the user?  Only one of these messages is useful -- "Email can't be blank."  
But it has a problem too.  On the form, the field label is "Administrator Email", so the message 
should be "Administrator email can't be blank".  (This could be very important if you had multiple 
email fields.)

The "Invitee is invalid" is because the Company object has a validates_associated :invitee which 
is actually a User object.  Great for a developer, complete gibberish to an end-user.  Additionally,
of course the "Email is too short", it's freaking *blank*!  Why show that redundant message?

Requires
========
ActiveSupport


Copyright (c) 2008 Relevance, Inc., released under the MIT license

=========================================================================================================

Input:
-------------------------------------------------------
5 errors prohibited this from being saved

There were problems with the following fields:

    * Invitee email must match an existing company's domain
    * Invitee is invalid
    * You can only invite users from your company
    * User requires either a vendor or a corporation
    * Email is not a valid e-mail address
-------------------------------------------------------

Desired output:
-------------------------------------------------------
An error prohibited this from being saved:
    * Email is not a valid e-mail address
-------------------------------------------------------

Input:
-------------------------------------------------------
4 errors prohibited this from being saved

There were problems with the following fields:

    * Invitee email must match an existing company's domain
    * Invitee is invalid
    * You can only invite users from your company
    * User requires either a vendor or a corporation
-------------------------------------------------------

Desired output:
-------------------------------------------------------
An error prohibited this from being saved:
    * You can only invite users from your company
-------------------------------------------------------

Solution rules:
<% 
  error_messages_for :company_invitation, :user do 
    suppress :company_invitation, :invitee, :invalid
    suppress :user, :base, "User requires either a vendor or a corporation"
    #suppress :user, :base, /either a vendor or a corporation/

    only_invite_from_own_company = error(:company_invitation, :base, "You can only invite users from your company")
    invalid_email_address = error(:user, :email, "is not a valid e-mail address")
    known_company_domain = error(:company_invitation, :invitee_email, "must match an existing company's domain")

    #trump :company_invitation, :subdomain, "can't be blank"), :over => [:already_taken, :special_characters]

    
    trump :company_invitation, :base, "You can only invite users from your company", :over => error(:user, :email, "is 
    not a valid e-mail address")
    trump :company_invitation, :base, :invite_only_from_own_company, :over => error(:user, :email, :invalid_email)
  
    trump invalid_email_address, :over => only_invite_from_own_company
    trump only_invite_from_own_company, :over => known_company_domain
    
    replace :user, :base, "some really, really bad error message", :with => "A much nicer message that includes 
    #{@some_local_variable}."
    add :some_field, :silliness_level, "has been exceeded"
  end
%>
=========================================================================================================

validates_each :email do
  self.errors.add(:email,  Error.new(:only_invite_from_own_company, "hey dude, you can't invite from people"))
end


=========================================================================================================
    
    
    
    
    
    
    
    
    
    
== only one model lets us not specify the model prefix on each error rule ==
<% 
  error_messages_for :company_invitation do 
    #suppress :invitee, "is invalid"
    suppress :invitee, :invalid
    ??? :invitee_email, "must match an existing company's domain"
    important :base, "You can only invite users from your company"
  end
%>



=========================================================================================================
From ActiveRecord's Validations API:
    @@default_error_messages = {
      :inclusion => "is not included in the list",
      :exclusion => "is reserved",
      :invalid => "is invalid",
      :confirmation => "doesn't match confirmation",
      :accepted  => "must be accepted",
      :empty => "can't be empty",
      :blank => "can't be blank",
      :too_long => "is too long (maximum is %d characters)",
      :too_short => "is too short (minimum is %d characters)",
      :wrong_length => "is the wrong length (should be %d characters)",
      :taken => "has already been taken",
      :not_a_number => "is not a number",
      :greater_than => "must be greater than %d",
      :greater_than_or_equal_to => "must be greater than or equal to %d",
      :equal_to => "must be equal to %d",
      :less_than => "must be less than %d",
      :less_than_or_equal_to => "must be less than or equal to %d",
      :odd => "must be odd",
      :even => "must be even"
    }