= WillFilter

will_filter is a Rails engine plugin that provides a GUI for filtering your ActiveRecord models.

== Preamble
 
If you ever had to build an admin tool for your web site that displayed a list of objects that can be filtered using 
various criteria, this plugin will make your life easier. Adding a filtered page can now be 
a matter of adding two lines of code - one to your controller and one to your view. See examples below.

== Installation Instructions

Add the following gems to your Gemfile: 

  gem 'will_filter', "~> 3.1.0" 
  gem 'kaminari'

And run:

  $ bundle

To configure and initialize will_filter engine, run the following commands: 

  $ rails generate will_filter  
  $ rake db:migrate 

At the top of your routes.rb file, add the following line:

  mount WillFilter::Engine => "/will_filter"


== Examples

To add a filtered result-set to your controller use the following method call:

  class UsersController < ApplicationController
  
    def index
      @users = User.filter(:params => params)    
    end
    
  end  

Note: 'User' is a Rails ActiveRecord model 

Now all you have to do is create a view for this action and add the following tag where you want the filter to be rendered:

  <%= will_filter_tag(@users) %>
	
And optionally you can do (for results table):
	
  <%= will_filter_table_tag(@users) %>

That's it. This will render a filter box with various conditions, operators and values for the model object you selected.

Below are a couple of screenshot of what the filter looks like when it is rendered on a page:

http://wiki.tr8n.org/images/e/e1/Wf1.png

http://wiki.tr8n.org/images/5/50/Wf2.png


This plugin comes with a dummy test project. To try out some of the examples, run the following commands:

  $ git clone git://github.com/berk/will_filter.git
  $ cd will_filter/test/dummy  
  $ rake db:migrate 
  $ rake samples:init
  $ rails server

Open your browser and point to: 

  http://localhost:3000

Live will_filter_examples application is running here:

http://wf.tr8n.org 

If you have any questions, comments or suggestions, email me at theiceberk@gmail.com

== Authors and credits

Authors::                Michael Berkovich