== Flagger

* Version: 0.9.5
* Release date: 31st May 2007

Do you often find yourself writing repetitive collections of methods on your
models that look like:

  class Order < ActiveRecord::Base
    def self.paid
      find_all_by_paid(true)
    end
    
    def self.unpaid
      find_all_by_paid(false)
    end
    
    def mark_as_paid
      update_attribute(:paid, true)
      # related tasks
    end
    
    def mark_as_unpaid
      update_attribute(:paid, false)
      # related tasks
    end
  end

This is good practise, as it keeps your column names wrapped up in the model
in case they need changing, rather than littering your controllers (or other
models) with them. And it increases code legibility, which is also a Good Thing.

The Flagger plugin allows <tt>ActiveRecord::Base</tt> to give you these methods
without you having to write any code. It uses <tt>method_missing</tt> hooks to
respond to methods not caught by <tt>ActiveRecord::Base</tt>'s built-in
<tt>method_missing</tt> code. It is designed to be used with boolean attributes,
that is, attributes that contain +true+/+false+, <tt>1</tt>/<tt>0</tt> or
<tt>"1"</tt>/<tt>"0"</tt> depending on column type. (Although, it is generally
not a good idea to use string/text columns for this type of data. You may encounter
problems if you attempt to do so, depending on which Rails version you are using.)


=== Boolean finders

Flagger allows you to use dynamic finders on boolean attributes without using
+find_all_by_+. So, using the above example, you can happily call <tt>Order.paid</tt>
to get all your paid orders, without defining the method yourself. In addition,
you can call <tt>Order.unpaid</tt>, and you will get back all the orders for which
<tt>paid == false</tt>. The full list of allowed prefixes is:

* +in+, +im+, +un+, +non+, +dis+, +de+, +ir+, and +not_+

If your model has an attribute whose name already begins with one of these,
Flagger will take this into account. For example, <tt>TallStory.implausible</tt>
returns all the <tt>TallStory</tt> records for which <tt>implausible == true</tt>.
You can chop off the prefix as well: <tt>TallStory.plausible</tt> does what
you'd expect.

Only one prefix will be added to or removed from the attribute name you use to
try and find matching attribute names. <tt>Fact.undeniable</tt> works if the +Fact+
model has an attribute called +undeniable+, +deniable+, +inundeniable+,
+imundeniable+ ... or +not_undeniable+. Attribute names are always checked in this
order, and Flagger will use the first one that exists. If no attribute match can be
found, the exception raised by <tt>ActiveRecord::Base</tt>'s built-in
<tt>method_missing</tt> code is reraised.

Attribute names can be chained together in a similar fashion to that allowed by
+find_by_+ and friends. You can use +and+ and +but+ to separate names, so you could write:

  orders = Order.paid_and_delivered
  orders.first.paid?
  #=> true
  orders.first.delivered?
  #=> true

  martinis = Cocktail.shaken_but_not_stirred
  martinis.first.shaken?
  #=> true
  martinis.first.stirred?
  #=> false


=== Dynamic markers

Attribute-based markers perform the converse task to boolean finders - they set
boolean attributes rather than retrieving based on them. They mark (flag) records
as having certain properties. Their syntax is very similar to that for finders:

  order = Order.find(:all).first
  order.mark_as_paid
  order.paid?
  #=> true
  order.mark_as_delivered_but_not_signed_for
  order.delivered?
  #=> true
  order.signed_for?
  #=> false

These methods do not save the attributes to the database. If you want to save
the attributes, end the method call with a <tt>!</tt>.

+mark_as_+ methods detect the column type for each attribute and set values
accordingly. +true+/+false+ are used for <tt>:boolean</tt> fields, <tt>1</tt>/<tt>0</tt>
for numeric fields, and <tt>"1"</tt>/<tt>"0"</tt> for <tt>:string</tt>/<tt>:text</tt> fields.

To perform tasks related to flagging, you can define +after_mark_as_+ methods on
your models. Each callback can include one attribute name (with or without prefixes
as appropriate) and can end with a <tt>!</tt> to denote whether it should be called
on database saves or not. For example, <tt>Order#after_mark_as_unpaid!</tt> will be
called after <tt>mark_as_unpaid!</tt>, <tt>mark_as_not_paid!</tt> and
<tt>mark_as_accepted_but_not_paid!</tt>, but not after <tt>mark_as_unpaid</tt> (no
exclamation mark). All the existing callbacks that apply to a +mark_as_+ call
will be called, but only if a change has been made to the relevant attribute.


=== Compatibility

Flagger has been tested successfully using MySQL 5 with Rails 1.1.6 and 1.2.0
through 1.2.3. Bug reports and test reports for other databases are welcome - my
email address is at the end of this file.


=== Notes

Flagger is an adjusted version of a patch[http://dev.rubyonrails.org/ticket/7735]
I submitted to Rails that didn't make it into the core. The source has been modified
from that version in a few places. Thanks to +tomafro+ for pointing me in the right
direction and plugging holes in my Ruby/Rails knowledge.

Clearly this plugin will not cover all possible use cases for flaggable models.
It is meant to try and provide some generally useful functionality out of the box,
and to eliminate the need to write code for the simpler cases. If it doesn't
quite do what you need, you can always roll your own methods to avoid hitting
+method_missing+.

One potentially useful addition would be support for OR-based finder conditions,
as in <tt>Lorry.red_or_yellow</tt>, although I suspect that including that would
be excessively complicating things - how would one handle
<tt>Lorry.red_and_yellow_or_green_but_not_blue</tt>? Does that mean <tt>(red && yellow)
|| (green && !blue)</tt>, or <tt>red && (yellow || green) && !blue</tt>?

Flagger is (c) 2007 James Coglan and is released under the terms of the MIT license.

Contact: james at jcoglan dot com