Permalink
Browse files

Add in some documentation

  • Loading branch information...
1 parent 0f4b5d6 commit 4d0cc8ce2ba89f8929ab9b0cd5fe4d7addd6a6dc @binarylogic committed Jun 15, 2009
@@ -1,6 +1,6 @@
module Searchlogic
module CoreExt
- module Proc
+ module Proc # :nodoc:
def self.included(klass)
klass.class_eval do
attr_accessor :searchlogic_arg_type
@@ -1,11 +1,12 @@
module Searchlogic
module NamedScopes
+ # Handles dynamically creating named scopes for associations.
module Associations
- def condition?(name)
+ def condition?(name) # :nodoc:
super || association_condition?(name) || association_alias_condition?(name)
end
- def primary_condition_name(name)
+ def primary_condition_name(name) # :nodoc:
if result = super
result
elsif association_condition?(name)
@@ -17,10 +18,13 @@ def primary_condition_name(name)
end
end
+ # Is the name of the method a valid name for an association condition?
def association_condition?(name)
!association_condition_details(name).nil?
end
+ # Is the ane of the method a valie name for an association alias condition?
+ # An alias being "gt" for "greater_than", etc.
def association_alias_condition?(name)
!association_alias_condition_details(name).nil?
end
@@ -1,5 +1,6 @@
module Searchlogic
module NamedScopes
+ # Handles dynamically creating named scopes for columns.
module Conditions
COMPARISON_CONDITIONS = {
:equals => [:is, :eq],
@@ -92,14 +93,19 @@ def primary_condition_name(name)
end
end
+ # Is the name of the method a valid condition that can be dynamically created?
def condition?(name)
primary_condition?(name) || alias_condition?(name)
end
+ # Is the name of the method a valid condition that can be dynamically created,
+ # AND is it a primary condition (not an alias). "greater_than" not "gt".
def primary_condition?(name)
!primary_condition_details(name).nil?
end
+ # Is the name of the method a valid condition that can be dynamically created,
+ # AND is it an alias condition. "gt" not "greater_than".
def alias_condition?(name)
!alias_condition_details(name).nil?
end
@@ -1,11 +1,12 @@
module Searchlogic
module NamedScopes
+ # Handles dynamically creating named scopes for orderin by columns.
module Ordering
- def condition?(name)
+ def condition?(name) # :nodoc:
super || order_condition?(name)
end
- def primary_condition_name(name)
+ def primary_condition_name(name) # :nodoc
if result = super
result
elsif order_condition?(name)
@@ -15,7 +16,7 @@ def primary_condition_name(name)
end
end
- def order_condition?(name)
+ def order_condition?(name) # :nodoc:
!order_condition_details(name).nil?
end
@@ -1,5 +1,18 @@
module Searchlogic
module RailsHelpers
+ # Creates a link that alternates between acending and descending. It basically
+ # alternates between calling 2 named scopes: "ascend_by_*" and "descend_by_*"
+ #
+ # By default Searchlogic gives you these named scopes for all of your columns, but
+ # if you wanted to create your own, it will work with those too.
+ #
+ # This helper accepts the following options:
+ #
+ # * <tt>:by</tt> - the name of the named scope. This helper will prepend this value with "ascend_by_" and "descend_by_"
+ # * <tt>:as</tt> - the text used in the link, defaults to whatever is passed to :by
+ # * <tt>:ascend_scope</tt> - what scope to call for ascending the data, defaults to "ascend_by_:by"
+ # * <tt>:descend_scope</tt> - what scope to call for descending the data, defaults to "descend_by_:by"
+ # * <tt>:params_scope</tt> - the name of the params key to scope the order condition by, defaults to :search
def order(search, options = {}, html_options = {})
options[:params_scope] ||= :search
options[:as] ||= options[:by].to_s.humanize
@@ -22,6 +35,8 @@ def order(search, options = {}, html_options = {})
link_to options[:as], url_for(options[:params_scope] => {:order => new_scope}), html_options
end
+ # Automatically makes the form method :get if a Searchlogic::Search and sets
+ # the params scope to :search
def form_for(*args, &block)
if search_obj = args.find { |arg| arg.is_a?(Searchlogic::Search) }
options = args.extract_options!
@@ -32,7 +47,9 @@ def form_for(*args, &block)
end
super
end
-
+
+ # Automatically adds an "order" hidden field in your form to preserve how the data
+ # is being ordered.
def fields_for(*args, &block)
if search_obj = args.find { |arg| arg.is_a?(Searchlogic::Search) }
args.unshift(:search) if args.first == search_obj
@@ -1,11 +1,33 @@
module Searchlogic
+ # A class that acts like a model, creates attr_accessors for named_scopes, and then
+ # chains together everything when an "action" method is called. It basically makes
+ # implementing search forms in your application effortless:
+ #
+ # search = User.search
+ # search.username_like = "bjohnson"
+ # search.all
+ #
+ # Is equivalent to:
+ #
+ # User.search(:username_like => "bjohnson").all
+ #
+ # Is equivalent to:
+ #
+ # User.username_like("bjohnson").all
class Search
+ # Responsible for adding a "search" method into your models.
module Implementation
+ # Returns a new Search object for the given model.
def search(conditions = {})
Search.new(self, scope(:find), conditions)
end
end
+ # Is an invalid condition is used this error will be raised. Ex:
+ #
+ # User.search(:unkown => true)
+ #
+ # Where unknown is not a valid named scope for the User model.
class UnknownConditionError < StandardError
def initialize(condition)
msg = "The #{condition} is not a valid condition. You may only use conditions that map to a named scope"
@@ -15,16 +37,21 @@ def initialize(condition)
attr_accessor :klass, :current_scope, :conditions
+ # Creates a new search object for the given class. Ex:
+ #
+ # Searchlogic::Search.new(User, {}, {:username_like => "bjohnson"})
def initialize(klass, current_scope, conditions = {})
self.klass = klass
self.current_scope = current_scope
self.conditions = conditions if conditions.is_a?(Hash)
end
+ # Returns a hash of the current conditions set.
def conditions
@conditions ||= {}
end
+ # Accepts a hash of conditions.
def conditions=(values)
values.each do |condition, value|
value.delete_if { |v| v.blank? } if value.is_a?(Array)

0 comments on commit 4d0cc8c

Please sign in to comment.