Permalink
Browse files

update docs

  • Loading branch information...
fizx committed Feb 2, 2010
1 parent 75dc67e commit 0626683b0f420c7b4619563b5071920108b7c04e
Showing with 195 additions and 22 deletions.
  1. +1 −0 LICENSE
  2. +0 −20 README
  3. +192 −0 README.rdoc
  4. +1 −1 Rakefile
  5. +1 −1 VERSION
View
@@ -1,4 +1,5 @@
Copyright (c) 2009 Kyle Maxwell
+Contributions from Mat Brown, John Barnette
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
View
20 README
@@ -1,20 +0,0 @@
-Changes:
-- Split the acts_as_solr, and websolr_rails versions of the gem. This is sunspot-only.
-- Fix the specific supported versions of sunspot/sunspot_rails
-- Web service call on boot to enforce the correct schema.xml.
-
-Using the experimental websolr sunspot client:
-
-sudo gem install websolr-sunspot_rails
-echo websolr-sunspot_rails >> .gems
-config.gem "websolr-sunspot_rails" # into config.environment.rb
-require 'sunspot/rails/tasks' >> Rakefile
-
-Edit config/sunspot.yml =>
-
-development:
- solr:
- hostname: localhost
- port: 8982
-
-Use sunspot_rails as usual.
View
@@ -0,0 +1,192 @@
+== About ==
+
+This is the gem to install for the supported version of sunspot_rails on websolr.
+
+== Installation ==
+
+ cd your_rails_app
+ sudo gem install websolr-sunspot_rails
+ config.gem "websolr-sunspot_rails" # into config.environment.rb
+ echo websolr-sunspot_rails >> .gems # if using Heroku
+ ./script/generate sunspot # Installs config/sunspot.yml
+ require 'sunspot/rails/tasks' >> Rakefile # Installs local development tasks
+
+== Usage
+
+=== Setup
+
+In order for an ActiveRecord model to be indexable and searchable, it must be
+configured for search. For example:
+
+ class Post < ActiveRecord::Base
+ searchable do
+ text :title, :body
+ integer :blog_id
+ time :updated_at
+ string :sort_title do
+ title.downcase.sub(/^(an?|the) /, '')
+ end
+ end
+ end
+
+See the documentation for Sunspot.setup for full details on what can go in the
+configuration block.
+
+=== Indexing
+
+By default, models are indexed whenever they are saved, and removed from the
+index whenever they are destroyed. This behavior can be disabled:
+
+ class Post < ActiveRecord::Base
+ searchable :auto_index => false, :auto_remove => false do
+ # setup...
+ end
+ end
+
+Note that <b>using the <code>:auto_remove</code> option is not recommended
+</b>, as destroying an object without removing it from the index will
+create an orphaned document in the index, which is a Bad Thing. Turning off
+<code>:auto_index</code> is perfectly safe if you prefer to manage indexing manually
+(perhaps using a background job).
+
+If you have disabled lifecycle indexing hooks, you can invoke indexing
+operations directly on your model:
+
+ post = Post.create
+ post.index
+ post.remove_from_index
+
+=== Committing
+
+When data is changed in Solr, it is initially stored in memory and not made
+available to the currently running searcher instance. Issuing a +commit+ to Solr
+will cause it to write the changes to disk, and instantiate a new searcher
+instance. This operation is fairly expensive, so rather than issuing a commit
+every time a document is added or removed, Sunspot::Rails issues a commit at
+the end of any request where data has been added to or removed from Solr. If
+you need to immediately issue a commit, bang!-versions of the methods are
+available:
+
+ post = Post.create
+ post.index!
+ # this is the same as...
+ post.index
+ Sunspot.commit
+
+When writing tests outside of the context of a controller request, you will want
+to use one of these two approaches.
+
+=== Searching
+
+Do it like this:
+
+ Post.search do
+ with :blog_id, 1
+ with(:updated_at).greater_than(Time.now - 2.weeks)
+ order :sort_title, :asc
+ paginate :page => 1, :per_page => 15
+ end
+
+See the documentation for <code>Sunspot.search</code> for all the options
+available in the search block, and the information available in the result
+block.
+
+=== Searching for IDs
+
+In some situations, you may want to get the IDs for models returned by a search
+without actually loading the models out of the database. For that, you can
+call +search_ids+, using the same block format as #search. This will return an
+array of IDs.
+
+
+=== Searching for multiple types
+
+Sunspot is entirely agnostic about whether searches are for one or more types;
+the only restriction is that columns used for restriction, ordering, etc. are
+defined in the same way for all types being searched. Sunspot::Rails does not
+provide any additional support for this, since there is not anything useful to
+be added, so just use the interface provided by Sunspot:
+
+ Sunspot.search(Post, Comment) do
+ with :blog_id, 1
+ order :created_at, :asc
+ end
+
+Be sure to check out the Sunspot documentation for all the details.
+
+=== Adding search functionality in mixins
+
+Sunspot does not require that search setup for a given class happen all in one
+place; it is perfectly acceptable to call the <code>Sunspot.setup</code> method
+more than once. This capability is particularly useful for adding search
+functionality in mixins. For instance, if you have a +Ratable+ module, you may
+wish to add additional search fields for searchable classes that mix in that
+module. For example:
+
+ module Ratable
+ def self.included(base)
+ if base.searchable?
+ base.searchable do
+ float :average_rating do
+ ratings.average(:value)
+ end
+ end
+ end
+ end
+ end
+
+Note the use of <code>base.searchable?</code> - this ensures that only classes
+that already have search enabled will have the additional configuration added.
+The above pattern requires that the class be declared searchable before the
+module is mixed in; other patterns (such as passing a :searchable option to an
+acts_as_-style declaration) may be more flexible.
+
+=== Utility methods
+
+If you need to completely reindex all of the instances of a given model class,
+you can issue:
+
+ Post.reindex
+
+If for some reason models get deleted from the database, but not from the index,
+they will become index orphans - not a good situation. To get IDs that exist in
+the index but not the database, you can use the +index_orphans+ method; to
+remove those documents from the index, use +clean_index_orphans+. Note that
+neither of these operations should be needed if Sunspot and Sunspot::Rails are
+used as intended.
+
+
+== Testing Solr integration using RSpec
+
+To disable the sunspot-solr integration for your active record models, add the
+following line to your spec_helper.rb
+
+require 'sunspot/spec/extension'
+
+This will disable all automatic after_save/after_destroy solr-requests generated
+via the #searchable method. This will not disable/mock explicit calls in your code.
+
+If you want to test the sunspot-solr integration with active record, you can
+reenable the after_save/after_destroy hooks by adding 'integrate_sunspot' in your
+examples.
+
+ describe Searches do
+ integrate_sunspot
+
+ before(:each) do
+ @movie = Factory.create :movie
+ end
+
+ it "should find a movie" do
+ Movie.search { keywords @movie.title }.first.should == @movie
+ end
+ end
+
+
+
+== Further Reading
+
+Reading the {Sunspot documentation}[http://outoftime.github.com/sunspot/docs] is
+highly recommended. Sunspot::Rails exists to wrap Sunspot with a Rails-friendly
+API, but almost all of the functionality you use in Sunspot::Rails is
+implemented in Sunspot.
View
@@ -9,7 +9,7 @@ begin
gem.description = %Q{websolr to sunspot_rails shim}
gem.email = "kyle@kylemaxwell.com"
gem.homepage = "http://github.com/fizx/websolr-sunspot_rails"
- gem.authors = ["Kyle Maxwell"]
+ gem.authors = ["Kyle Maxwell", "John Barnette", "Mat Brown"]
gem.add_dependency "sunspot_rails", "0.11.4"
gem.add_dependency "rest-client"
gem.add_development_dependency "rspec"
View
@@ -1 +1 @@
-0.1.0
+0.9.0

0 comments on commit 0626683

Please sign in to comment.