websolr-sunspot_rails 0.1.0 → 0.9.0

data/LICENSE

@@ -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

data/README.rdoc

@@ -1,26 +1,192 @@
-= websolr-rails
+== About ==
 
-This overrides Sunspot to use the value of the environment variable 
-WEBSOLR_URL as the Solr Search server, provided that it's defined.
+This is the gem to install for the supported version of sunspot_rails on websolr.
 
-After installing the gem, you can include websolr-rails in your 
-app by either starting the webapp like:
+== Installation == 
 
-  WEBSOLR_URL=http://index.websolr.com/solr/<api-key> ./script/server
-  
-Or, you can put the following in /environment/production.rb, or an
-initializer, etc:
+  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      
 
-  # production.rb
-  ENV["WEBSOLR_URL"] = "http://index.websolr.com/solr/<api-key>"
+== Usage
 
-  # WEBSOLR_URL must already be defined.
-  require "websolr-sunspot_rails"
+=== Setup
 
-== Semantic Versioning
+In order for an ActiveRecord model to be indexable and searchable, it must be
+configured for search. For example:
 
-This library obeys the definition of "Semantic Versioning" at http://semver.org/.  YMMV with its dependencies.
+  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
 
-== Copyright
+See the documentation for Sunspot.setup for full details on what can go in the
+configuration block.
 
-Copyright (c) 2009 Kyle Maxwell. See LICENSE for details.
+=== 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.

data/Rakefile

@@ -9,12 +9,10 @@ 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.add_dependency "plain_option_parser", ">= 0"
-    gem.add_dependency "sunspot", "=0.10.8"
-    gem.add_dependency "sunspot_rails", "=0.11.5"
+    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", ">= 0"
+    gem.add_development_dependency "rspec"
   end
   Jeweler::GemcutterTasks.new
 rescue LoadError

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.9.0

data/lib/websolr-sunspot_rails.rb

@@ -1,12 +1,5 @@
-require "rubygems"
-gem "sunspot", :version => "0.10.8"
-gem "sunspot_rails", :version => "0.11.5"
-
-# Post-require hooks and sunspot if WEBSOLR_URL is defined.
 if ENV["WEBSOLR_URL"]
   
-  CLIENT_KEY = "sunspot-0.10"
-  
   require "rest_client"
   require "uri"
   require "sunspot/rails"
@@ -15,10 +8,7 @@ if ENV["WEBSOLR_URL"]
   require "sunspot/rails/request_lifecycle"
   
   api_key = ENV["WEBSOLR_URL"][/[0-9a-f]{11}/] or raise "Invalid WEBSOLR_URL: bad or no api key"
-  print "Setting schema to #{CLIENT_KEY}..."
-  STDOUT.flush
-  RestClient.post("http://www.websolr.com/schema/#{api_key}", :client => CLIENT_KEY)
-  puts "done"
+  RestClient.post("http://www.websolr.com/schema/#{api_key}", :client => "sunspot-0.10")
   
   module Sunspot #:nodoc:
     module Rails #:nodoc:
@@ -71,7 +61,7 @@ if ENV["WEBSOLR_URL"]
     end
   end
   
-  
+  # This code makes saves go though even though solr is down.
   module Sunspot
     module Rails 
       module Searchable
@@ -94,4 +84,4 @@ if ENV["WEBSOLR_URL"]
       end
     end
   end 
-end
+end

data/websolr-sunspot_rails.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{websolr-sunspot_rails}
-  s.version = "0.1.0"
+  s.version = "0.9.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Kyle Maxwell"]
-  s.date = %q{2010-01-26}
+  s.authors = ["Kyle Maxwell", "John Barnette", "Mat Brown"]
+  s.date = %q{2010-02-02}
   s.description = %q{websolr to sunspot_rails shim}
   s.email = %q{kyle@kylemaxwell.com}
   s.extra_rdoc_files = [
@@ -37,22 +37,16 @@ Gem::Specification.new do |s|
     s.specification_version = 3
 
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<plain_option_parser>, [">= 0"])
-      s.add_runtime_dependency(%q<sunspot>, ["= 0.10.8"])
-      s.add_runtime_dependency(%q<sunspot_rails>, ["= 0.11.5"])
+      s.add_runtime_dependency(%q<sunspot_rails>, ["= 0.11.4"])
       s.add_runtime_dependency(%q<rest-client>, [">= 0"])
       s.add_development_dependency(%q<rspec>, [">= 0"])
     else
-      s.add_dependency(%q<plain_option_parser>, [">= 0"])
-      s.add_dependency(%q<sunspot>, ["= 0.10.8"])
-      s.add_dependency(%q<sunspot_rails>, ["= 0.11.5"])
+      s.add_dependency(%q<sunspot_rails>, ["= 0.11.4"])
       s.add_dependency(%q<rest-client>, [">= 0"])
       s.add_dependency(%q<rspec>, [">= 0"])
     end
   else
-    s.add_dependency(%q<plain_option_parser>, [">= 0"])
-    s.add_dependency(%q<sunspot>, ["= 0.10.8"])
-    s.add_dependency(%q<sunspot_rails>, ["= 0.11.5"])
+    s.add_dependency(%q<sunspot_rails>, ["= 0.11.4"])
     s.add_dependency(%q<rest-client>, [">= 0"])
     s.add_dependency(%q<rspec>, [">= 0"])
   end

metadata

@@ -1,37 +1,19 @@
 --- !ruby/object:Gem::Specification 
 name: websolr-sunspot_rails
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.9.0
 platform: ruby
 authors: 
 - Kyle Maxwell
+- John Barnette
+- Mat Brown
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2010-01-26 00:00:00 -08:00
+date: 2010-02-02 00:00:00 -08:00
 default_executable: 
 dependencies: 
-- !ruby/object:Gem::Dependency 
-  name: plain_option_parser
-  type: :runtime
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
-    version: 
-- !ruby/object:Gem::Dependency 
-  name: sunspot
-  type: :runtime
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
-    requirements: 
-    - - "="
-      - !ruby/object:Gem::Version 
-        version: 0.10.8
-    version: 
 - !ruby/object:Gem::Dependency 
   name: sunspot_rails
   type: :runtime
@@ -40,7 +22,7 @@ dependencies:
     requirements: 
     - - "="
       - !ruby/object:Gem::Version 
-        version: 0.11.5
+        version: 0.11.4
     version: 
 - !ruby/object:Gem::Dependency 
   name: rest-client