Module: SearchableRecord::ClassMethods

Defined in:
lib/searchable_record/core.rb

Instance Method Summary collapse

Instance Method Details

#find_queried(extend, query_params, rules, options = { }) ⇒ Object

Description

Parses the query parameters the client has given in the URL of the HTTP request. With the query parameters, the client may set a limit, an offset, or an ordering for the items in the search result. In addition, the client may limit the output by allowing only certain records that match to specific patterns.

What the client user is allowed to query is defined by specific rules passed to the method as a hash argument. Query parameters that are not explicitly stated in the rules are silently discarded.

Essentially, the method is a frontend for ActiveRecord::Base#find. The method

  1. parses the query parameters the client has given in the URL for the HTTP request (query_params) against the rules (rules), and

  2. calls find with the parsed options.

Parsing rules

The parsing rules must be given as a hash. The recognized keys are the following:

  • :limit, allowing limiting the number of matching items (the same effect as with find). The value for the key is irrelevant; use nil. The rule enables query parameter “limit” that accepts an integer value.

  • :offset, allowing skipping matching items (the same effect as with find). The value for the key is irrelevant; use nil. The rule enables query parameter “offset” that accepts an integer value.

  • :sort, which determines the ordering of matching items (the same effect as with the :order option of find). The value is a hash of "<parameter_value>" => "<table>.<column>" pairs. The rule enables query parameter “sort” that accepts keys from the hash as its legal values.

  • :rsort, for reverse sort. Uses the rules of :sort; thus, use nil as the value if you want to enable “rsort” query parameter.

  • :since, which sets a lower timedate limit. The value is either a string naming the database table column that has timestamps (using the type from default settings’ :cast_since_as entry) or a hash that contains entries like :column => "<table>.<column>" and :cast_as => "<sql_timedate_type>". The rule enables query parameter “since” that accepts timedate values.

  • :until, which sets an upper timedate limit. It is used like :since.

  • :patterns, where the value is a hash containing patterns. The keys in the hash correspond to additional query parameters, while the corresponding values to the keys correspond to database table columns. For each pattern, the value is either directly a string, or a hash containing an entry like :column => "<table>.<column>". A pattern’s hash may contain two optional entries in addition to :column: :converter => lambda { |val| <conversion_operation_for_val> } and :operator => "<sql_pattern_operator>".

    • :converter expects a block that modifies the input value; if the key is not given, the converter specified in :pattern_converter in the default settings is used instead.

    • :operator specifies a custom match operator for the pattern; if the key is not given, the operator specified in :pattern_operator in the default settings is used instead.

If both sort and rsort parameters are given in the URL and both are allowed query parameter by the rules, sort is favored over rsort. Unlike with sort and rsort rules (rsort uses the rules of sort), the rules for since and until are independent from each other.

For usage examples, see the example in README.txt and the specs that come with the plugin.

Default settings for rules

The default settings for the rules are accessible and modifiable by calling the method searchable_record_settings. The settings are stored as a hash; the following keys are recognized:

  • :cast_since_as,

  • :cast_until_as,

  • :pattern_operator, and

  • :pattern_converter.

See the parsing rules above how the default settings are used.

Arguments

extend

The same as the first argument to find (such as :all).

query_params

The (unsafe) query parameters from the URL as a hash.

rules

The parsing rules as a hash.

options

Additional options for find, such as :include => [ :an_association ].

Return

The same as with ActiveRecord::Base#find.



121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/searchable_record/core.rb', line 121

def find_queried(extend, query_params, rules, options = { })
  # Ensure the proper types of arguments.
  query_params = query_params.to_hash
  rules = rules.to_hash
  options = options.to_hash

  query_params = preserve_allowed_query_params(query_params, rules)

  unless query_params.empty?
    parse_offset(options, query_params)
    parse_limit(options, query_params)
    parse_order(options, query_params, rules)
    parse_conditional_rules(options, query_params, rules)
  end

  logger.debug("find_queried: query_params=<<#{query_params.inspect}>>, resulted options=<<#{options.inspect}>>")

  self.find(extend, options)
end