search_magic 0.1.1 → 0.2.0

data/README.textile

@@ -1,178 +0,0 @@
-h1. SearchMagic
-
-SearchMagic provides full-text search capabilities to "mongoid":http://github.com/mongoid/mongoid documents, embedded documents, and referenced documents with a clean, consistent, and easy to use syntax. Searching can be performed on either word fragments, such as *foo*, or can use a selector-syntax, *foo:bar*, to target which fields of the document the search is to be restricted to.
-
-h2. Installation
-
-SearchMagic is built on top of mongoid; in all likelihood, it will only work with versions greater than or equal to _2.0.0_. The project can be installed as a gem on a target system:
-
-bc. gem install search_magic
-
-For environments where bundler is being used, it can be installed by adding the following to your Gemfile and running @bundle@.
-
-bc. gem 'search_magic'
-
-h2. Getting Started
-
-h3. Adding FullTextSearch capabilities
-
-Adding FullTextSearch is as simple as including the appropriate module into a mongoid document and defining which fields are to be searchable. In the following example, the *SearchMagic::FullTextSearch* module is included and each field of the model is made searchable.
-
-bc.. class Address
-  include Mongoid::Document
-  include SearchMagic
-  field :street
-  field :city
-  field :state
-  field :post_code
-  embedded_in :person
-  
-  search_on :street
-  search_on :city
-  search_on :state
-  search_on :post_code
-end
-
-p. At this point, *Address* can be searched by calling its _*:search_for*_ method:
-
-bc. Address.search_for("state:ca")
-
-It is also possible to sort models on fields which have been marked as searchable through the _*:arrange*_ method:
-
-bc. Address.arrange(:state, :asc)
-
-h3. :search_on
-
-Fields that are made searchable by :search_on have their values cached in an embedded array within each document. This array, *:searchable_values*, should contain entries of the form *field_name:value*. The selector, *field_name*, represents a filter which can be used when searching to narrow the search space; it can be manually renamed by passing the *:as* option to :search_on:
-
-bc. search_on :post_code, :as => :zip_code 
-
-The example in the previous section showcased using :search_on on basic *Mongoid::Document* fields. It can, however, be used on fields within a document which denote an association.
-
-bc.. class Person
-  include Mongoid::Document
-  include SearchMagic
-  field :name
-  embeds_one :address
-  
-  search_on :name
-  search_on :address
-end
-
-p. When an association is searched on, all of its searchable fields are automatically made searchable in the first document. In the previous example, this means that the four fields of *Address*, @[:street, :city, :state, :post_code]@ are now searchable from within *Person*. As such, each association will end up adding entries into the *:searchable_values* array. The searchable fields which are introduced from an association can be restricted by use of the *:only* and *:except* options, which may either take an array or an individual field name:
-
-bc. search_on :address, :only => [:street, :state]
-search_on :address, :except => :post_code
-
-By default, an association's fields will be prefixed by name of the association. Therefore, the previous example would add entries to *:searchable_values* with the selectors @[:address_street, :address_city, :address_state, :address_post_code]@. The *:as* option alters the prefix:
-
-bc. search_on :address, :as => :location # results in :location_street, :location_city, ...
-
-It is also possible to prevent the prefix from being added to each absorbed searchable field through use of the *:skip_prefix* option:
-
-bc. search_on :address, :skip_prefix => true # results in :street, :city, ...
-
-:skip_prefix and :as cannot be used concurrently: :skip_prefix will always take precedence. 
-
-Values added to *:searchable_values* automatically are split on whitespace and have their punctuation removed. For most cases, searches performed on models are not going to need punctuation support. However, if it is desired to keep the punctuation present on a particular field, that can easily be done through the *:keep_punctuation* option:
-
-bc.. class Asset
-  include Mongoid::Document
-  include SearchMagic
-  field :tags, :type => Array
-  
-  search_on :tags, :keep_punctuation => true
-end
-
-p. Now all entries within *:searchable_values* for *:tags* will retain meaningful punctuation. The previous example is interesting for another reason: embedded arrays are handled specially. Specifically, the selector for an embedded array will be singularized. In the case of the previous example, this would result in a selector of "tag".
-
-Two documents may search on each other's fields; doing so will cause each document to only search upon those fields stemming from itself once. Given the following example, _Foo_ would be able to search on @[:name, :bar_value]@, while _Bar_ would be able to search on @[:value, :foo_name]@.
-
-bc.. class Foo
-  include Mongoid::Document
-  include SearchMagic
-  field :name
-  references_many :bars
-  search_on :name
-  search_on :bars
-end
-
-class Bar
-  include Mongoid::Document
-  include SearchMagic
-  field :value
-  referenced_in :foo
-  search_on :value
-  search_on :foo
-end
-
-Finally, it should be noted that nesting of searchable documents is possible. If a given document searches on an association with another document which, in and of itself, searches on a third document, the first automatically has access to the third document's searchable fields.
-
-bc.. class Part
-  include Mongoid::Document
-  include Mongoid::Timestamps
-  include SearchMagic
-  field :serial
-  references_in :part_number
-  
-  search_on :serial
-  search_on :part_number, :skip_prefix => true
-end
-
-class PartNumber
-  include Mongoid::Document
-  include SearchMagic
-  field :value
-  references_many :parts
-  referenced_in :part_category
-  
-  search_on :number
-  search_on :part_category, :as => :category
-end
-
-class PartCategory
-  include Mongoid::Document
-  include SearchMagic
-  field :name
-  references_many :part_numbers
-  
-  search_on :name
-end
-
-p. *PartNumber* will be able to search on both _:number_ and _:category_name_. *Part*, on the other hand, will absorb all of the searchable fields of PartNumber, including its associations. So, it can be searched on _:serial_, _:number_, and _:category_name_.
-
-h3. :search_for
-
-Searching a model with SearchMagic is simple: each model gains a class method called _*:search_for*_ which accepts one parameter, the search pattern. This method is a "mongoid scope":http://mongoid.org/docs/querying/; it will always return a criteria object after executing. As such, it plays nicely with other scopes on your models.
-
-SearchMagic expects the incoming _pattern_ to be a string containing whitespace delimited phrases. Each phrase can either be a single word, or a _selector:value_ pair. Multiple phrases will narrow the search field: each additional phrase places an additional requirement on a matching document. Single word phrases are matched across all entries in a model's _:searchable_values_ array. The pairs, on the other hand, restrict the search for _value_ against only those entries which match _selector_. In either case, _word_ or _value_ may contain fragments of whole entries stored within _:searchable_values_.
-
-Using the models defined in the previous section, the following searches are all perfectly valid:
-
-bc. Part.search_for("table") # full text search on "table"
-Part.search_for("category_name:table") # restricts the search for "table" to "category_name"
-Part.search_for("bike serial:b1234") # full text search on "bike", with an extra requirement that the serial be "b1234"
-
-As _*:search_for*_ is a scope, it can be called on any previous scope within the call chain:
-
-bc. Part.where(:created_at.gt => 1.day.ago.time).search_for("table")
-
-_*:search_for*_ can be called multiple times within the same scope chain. Doing so will append each successive pattern to the previous searches. Effectively, this is the same as performing a single _*:search_for*_ with whitespace delimited terms in the pattern. To make such expressions slightly more readable, _*:search_for*_ is aliased as _*:and_for*_:
-
-bc. Part.search_for("bike").and_for("serial:b1234")
-
-h3. :arrange
-
-SearchMagic also provides a utility scope for arranging the model by the searchables defined within it. This method, _*:arrange*_, has one required parameter specifying the searchable to sort on and one optional parameter specifying the sort direction. (If the second parameter is omitted, it will default to ascending.)
-
-bc. Part.arrange(:serial)
-Part.arrange(:serial, :asc) # same as last example
-Part.arrange(:category_name, :desc) # arrange the parts in descending order by :category_name
-
-As mentioned, _*:arrange*_ is a scope, so it can be chained with other scopes on a given model:
-
-bc. Part.search_for("category_name:table").arrange(:serial, :asc)
-
-h2. Problems? Comments?
-
-Feel free to add an "issue on GitHub":search_magic/issues or fork the project and send a pull request. I'm always looking for new ways of bending hardware to my will, so suggestions are welcome.