History

ActiveRecord::MultiConditions¶

MultiConditions is a simple ActiveRecord plugin for storing ActiveRecord find conditions and make complex queries painless.

DISCONTINUED PROJECT: as of April 2009, I decided to discontinue the development of this library to concentrate my efforts on other projects.

If you are looking for a good alternative, I encourage you to have a look at Ben Johnson’s SearchLogic library. SearchLogic provides all ActiveRecord::Multiconditions features along with many other cool stuff.

Overview¶

This plugin doesn't replace ActiveRecord#with_scope method, nor the basic :condition usage but extends it with the ability of storing illimitate conditions in multiple step.

 1 class Task < ActiveRecord::Base; end
 2 
 3 # create a new MultiConditions instance
 4 conditions = Task.multicondition
 5 
 6 # append a condition
 7 conditions.append_condition(['active = ? AND query LIKE ?', true, '%foo'])
 8 
 9 # conditional-append a condition 
10 conditions.append_condition(['name = ?', 'aname']) if admin?
11 
12 # get the final condition list ...
13 conditions.to_conditions
14 # => "active = true AND query LIKE '%foo' AND name = 'aname'" 
15 
16 # ... compatible with ActiveRecord finders
17 Task.find(:all, :conditions => conditions.to_conditions)

Dependencies¶

Ruby 1.8.6
ActiveRecord >= 2.0 (tested up to AR 2.3)

If you want to run the test suite:

sqlite3-ruby

Download and Installation¶

Installing ActiveRecord MultiConditions as a GEM is probably the best and easiest way. You must have {RubyGems}[http://rubyforge.org/projects/rubygems/] installed for the following instruction to work:

$ sudo gem install activerecord-multiconditions

To install the library manually grab the source code from the website, navigate to the root library directory and enter:

$ sudo ruby setup.rb

If you need the latest development version you can download the source code from the GIT repositories listed above. Beware that the code might not as stable as the official release.

Usage¶

First, don't forget to require the library.

1 require 'rubygems'
2 require 'activerecord-multiconditions'

Now MultiConditions object is automatically available as subclass of any ActiveRecord object.

1 class Task < ActiveRecord::Base
2   # your Task model
3 end
4 
5 multiconditions = Task.multiconditions(:status => 'active')
6 # => new instance

Creating a new instance¶

If you use ActiveRecord from Rails, this is just a matter of creating a new Model.

1 # create the Task model
2 class Task < ActiveRecord::Base
3 end

Now MultiConditions is automatically available within your Task namespace.
You can use it in whatever class method, for example:

1 class Task < ActiveRecord::Base
2 
3   def complex_search()
4     c = multiconditions(:foo => 'bar')
5     Task.find(:all, c.to_conditions)
6   end
7 
8 end

But you can create a new instance from an other library, class or model as well.
Just remember to initialize MultiConditions from its own namespace.

 1 class Foo
 2   class << self
 3     def my_cool_conditions
 4       Task::multiconditions(:foo => 1).to_conditions
 5     end
 6   end
 7 end
 8 
 9 Foo.my_cool_conditions
10 # => 'foo = 1'

Appending conditions¶

You can append new conditions with the following methods, passing the conditions you want to append or prepend as parameters.

#append_condition
#prepend_condition

See Condition Types section to lean more about supported objects.

conditions.append_condition(['active = ? AND query LIKE ?', true, '%foo']
  conditions.prepend_condition(['name = ?', 'aname']

conditions.to_conditions

=> "name = 'aname' AND active = true AND query LIKE '%foo'"

Condition types¶

The MultiConditions object accepts any type of conditions supported by ActiveRecord, including Strings, Arrays and Hashes, and merges them alltogether just before sending the final :condition value to ActiveRecord search method.

1 conditions.append_conditions(:foo => 1, :bar => 2)
2 conditions.append_conditions('active = 1')
3 conditions.append_conditions(['name LIKE ?', '%foo'])
4 
5 conditions.to_conditions 
6 # => 'foo = 1 AND :bar = 2 AND active = 1 AND name LIKE '%foo'

See ActiveRecord::Base#find documentation for more conditions examples.

Important¶

Once loaded, this library become part of ActiveRecord package and it creates its own namespace at ActiveRecord::Base::MultiConditions.

1 require 'multi_conditions'

For various reason, you cannot initialize a new ActiveRecord::Base::MultiConditions
but you MUST initialize a MultiConditions instance from a Model or
using the ActiveRecord::Base#multiconditions method (preferred way).

 1 # The wrong way
 2 # raises Message: <"undefined method `abstract_class?' for Object:Class">
 3 ActiveRecord::Base::MultiConditions.new
 4 
 5 # The right way
 6 class Model < ActiveRecord::Base
 7   def a_method()
 8     c = MultiConditions.new(Model, ['foo = ?', 'bar'])
 9     find(:all, :conditions => c.to_conditions)
10   end
11 end
12 
13 # The best way
14 class Model < ActiveRecord::Base
15 end
16 conditions = Model.multiconditions(['foo = ?', 'bar'])

Author¶

Simone Carletti <weppos@weppos.net>

Resources¶

FeedBack and Bug reports¶

Feel free to email "me":weppos@weppos.net with any questions or feedback.
Please use the Ticket System to submit bug reports or feature request.

Changelog¶

See the CHANGELOG.rdoc file for details.

ActiveRecord::MultiConditions

Wiki