Class: MetaSearch::Where

Wheres are how MetaSearch does its magic. Wheres have a name (and possible aliases) which are appended to your model and association attributes. When you instantiate a MetaSearch::Builder against a model (manually or by calling your model‘s search method) the builder responds to methods named for your model‘s attributes and associations, suffixed by the name of the Where.

These are the default Wheres, broken down by the types of ActiveRecord columns they can search against:

All data types

equals (alias: eq) - Just as it sounds.
does_not_equal (aliases: ne, noteq) - The opposite of equals, oddly enough.
in - Takes an array, matches on equality with any of the items in the array.
not_in (aliases: ni, notin) - Like above, but negated.
is_null - The column has an SQL NULL value.
is_not_null - The column contains anything but NULL.

Strings

contains (aliases: like, matches) - Substring match.
does_not_contain (aliases: nlike, nmatches) - Negative substring match.
starts_with (alias: sw) - Match strings beginning with the entered term.
does_not_start_with (alias: dnsw) - The opposite of above.
ends_with (alias: ew) - Match strings ending with the entered term.
does_not_end_with (alias: dnew) - Negative of above.

Numbers, dates, and times

greater_than (alias: gt) - Greater than.
greater_than_or_equal_to (aliases: gte, gteq) - Greater than or equal to.
less_than (alias: lt) - Less than.
less_than_or_equal_to (aliases: lte, lteq) - Less than or equal to.

Booleans

is_true - Is true. Useful for a checkbox like "only show admin users".
is_false - The complement of is_true.

Non-boolean data types

is_present - As with is_true, useful with a checkbox. Not NULL or the empty string.
is_blank - Returns records with a value of NULL or the empty string in the column.

So, given a model like this…

  class Article < ActiveRecord::Base
    belongs_to :author
    has_many :comments
    has_many :moderations, :through => :comments
  end

…you might end up with attributes like title_contains, comments_title_starts_with, moderations_value_less_than, author_name_equals, and so on.

Additionally, all of the above predicate types also have an _any and _all version, which expects an array of the corresponding parameter type, and requires any or all of the parameters to be a match, respectively. So:

  Article.search :author_name_starts_with_any => ['Jim', 'Bob', 'Fred']

will match articles authored by Jimmy, Bobby, or Freddy, but not Winifred.

Methods

add all evaluate format_param get initialize_wheres new skip_compounds? splat_param? validate

Attributes

 aliases
 cast
 formatter
 name
 predicate
 types
 validator

Public Class methods

add(*args)

At application initialization, you can add additional custom Wheres to the mix. in your application‘s config/initializers/meta_search.rb, place lines like this:

  MetaSearch::Where.add :between, :btw,
    :predicate => :in,
    :types => [:integer, :float, :decimal, :date, :datetime, :timestamp, :time],
    :formatter => Proc.new {|param| Range.new(param.first, param.last)},
    :validator => Proc.new {|param|
      param.is_a?(Array) && !(param[0].blank? || param[1].blank?)
    }

The first options are all names for the where. Well, the first is a name, the rest are aliases, really. They will determine the suffix you will use to access your Where.

types is an array of types the comparison is valid for. The where will not be available against columns that are not one of these types. Default is ALL_TYPES, Which is one of several MetaSearch constants available for type assignment (the others being DATES, TIIMES, STRINGS, and NUMBERS).

predicate is the Arel::Attribute predication (read: conditional operator) used for the comparison. Default is :eq, or equality.

formatter is the Proc that will do any formatting to the variables to be substituted. The default proc is {|param| param}, which doesn‘t really do anything. If you pass a string, it will be +eval+ed in the context of this Proc.

For example, this is the definition of the "contains" Where:

  ['contains', 'like', {:types => STRINGS, :predicate => :matches, :formatter => '"%#{param}%"'}]

Be sure to single-quote the string, so that variables aren‘t interpolated until later. If in doubt, just use a Proc.

validator is the Proc that will be used to check whether a parameter supplied to the Where is valid. If it is not valid, it won‘t be used in the query. The default is {|param| !param.blank?}, so that empty parameters aren‘t added to the search, but you can get more complex if you desire, like the one in the between example, above.

splat_param, if true, will cause the parameters sent to the predicate in question to be splatted (converted to an argument list). This is not normally useful and defaults to false, but is used when automatically creating compound Wheres (*_any, *_all) so that the Arel attribute method gets the correct parameter list.

skip_compounds will prevent creation of compound condition methods (ending in any or all) for situations where they wouldn‘t make sense, such as the built-in conditions is_true and is_false.

cast will override the normal cast of the parameter when using this Where condition. Normally, the value supplied to a condition is cast to the type of the column it‘s being compared against. In cases where this isn‘t desirable, because the value you intend to accept isn‘t the same kind of data you‘ll be comparing against, you can override that cast here, using one of the standard DB type symbols such as :integer, :string, :boolean and so on.

all()

Returns the complete array of Wheres

get(method_id_or_predicate)

Get the where matching a method or predicate.

initialize_wheres()

Set the wheres to their default values, removing any customized settings.

new(where)

Public Instance methods

evaluate(relation, attributes, param)

Evaluate the Where for the given relation, attribute, and parameter(s)

format_param(param)

Format a parameter for searching using the Where‘s defined formatter.

skip_compounds?()

splat_param?()

validate(param)

Validate the parameter for use in a search using the Where‘s defined validator.