repertoire-faceting 0.5.5 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8b37dce6950784df35020d3362c8824672bf3d53
-  data.tar.gz: 2f2cf88eeb90f133e2f4c92029939824e8d9d761
+  metadata.gz: 9e727bb33feffd5e77e77263ecc16f74666ab1d5
+  data.tar.gz: 087228d40ae3e1faa88de3d285ba4350d81f1411
 SHA512:
-  metadata.gz: 2cfb4a8f2e0bea97e2e4318f3a8ba348cb9ce4cb761442351372682cf1eea8e4d0d6365aa88166187192e71a0e9233e041de514426a3a6de55203d431e4224c2
-  data.tar.gz: dcb0eaf02b7e5604e2b489ee6c551c7da1a783764178825c84d75f9de33d158853700953731b2c9a69a86246087179b56fcb1795ff00a31197d7a5e58eb444f1
+  metadata.gz: e8df6396c41f96dba9822c2f694e79f42e108651c53b9fa49f5bb1032769f7edc8006ee0d5c53f93c1fc5a6612ed3ece7b3380372554ed0f5e61567ac7f47944
+  data.tar.gz: f3a3b38089d75cc360aa2f99119eeb4955a9c69eeba5e4fc94878523dbed0dc853852df17fa51a2ef6e7f0301aad875a6b2bdf1ac0365e92c31372efe52c978e

data/FAQ

@@ -2,12 +2,23 @@
 
 == General questions
 
-*Q* Can I use Rails 3 migrations with Repertoire Faceting?
+*Q* Can I use Rails migrations with Repertoire Faceting?
 
 *A* In general, yes. However, Rails' developers recommend you use the database's native dump format rather than schema.rb. Put the following line in environment.rb:
 
       config.active_record.schema_format = :sql
 
+    You can also use migrations to install the API in your database. A simple example:
+
+    def self.change
+      reversible do |dir
+        dir.up   { execute('CREATE EXTENSION faceting') }
+        dir.down { execute('DROP EXTENSION faceting CASCADE') }
+      end
+    end
+
+	In cases where you do not have superuser access to the deployment host (e.g. Heroku) and so cannot run "rake db:faceting:extensions:install", you can get use the connection's "faceting_api_sql" method to load the API by hand. See the repertoire-faceting-example application's migrations for a concrete example.
+
 
 == About facet indexing and the signature SQL type
 
@@ -18,7 +29,7 @@
 
 *Q* My facets are empty.
 
-*A* Make sure the facet indices aren't empty.  Running '<model>.update_indexed_facets([])' from the console will drop them all.
+*A* Make sure the facet indices aren't empty.  Running '<Model>.index_facets([])' from the Rails console will drop them all.
 
 
 *Q* Can I facet over multiple models?
@@ -28,31 +39,26 @@
 
 *Q* Why a new native PostgreSQL type?
 
-*A* As of PostgreSQL 8.4, there is no support for population counts in either blobs or bitstrings. Neither of these built-in types provides both the bitset and I/O functions required for faceting.
+*A* As of PostgreSQL 9.3, we have a binding for the Repertoire in-database faceting functions, based on VARBIT strings. However, it is many times slower than using the C-language signature type.
 
 
 == About the ajax faceting widgets
 
 
-*Q* Rails 3 is sending JSON data in a format that my javascript widgets don't understand.
+*Q* Rails is sending JSON data in a format that my javascript widgets don't understand.
 
 *A* Put the following line in config/application.rb:
 
    config.active_record.include_root_in_json = false
 
 
-*Q* A web page from the default Rails app refuses to load the faceting widgets.
-
-*A* Repertoire Faceting widgets are based on JQuery, which is incompatible with Prototype.  You should remove prototype.js and rails.js from the javascripts directory, and delete the <%= javascript_include_tag :defaults %> line from application.html.erb.
-
-
 *Q* How do I send page-specific data (for example, a search field) to the webservice with the facet widgets' data?
 
 *A* If you provide a function to the facet_context plugin, it will merge the params you return before dispatching to the webservice, e.g.
 
    $('#invoices').facet_context(function() {
-     return { 
-       search: $("#search_field").val() 
+     return {
+       search: $("#search_field").val()
      };
    });
 
@@ -64,7 +70,7 @@
 *Q* How do I make one-time, minor changes to the behaviour of a widget?  For example, I want to add a control.
 
 *A* Use the inject option, which is part of the base functionality.  Your injector function receives a reference to the widget's jquery element and to the widget javascript object.  Use jquery to add your control's markup, then register an event handler to add its behaviour.  For example, this injector adds a clear-all button in the title:
-   
+
    $('#genre').facet({
       injectors: {
         '.title .controls' : function(self, data) { $(this).append('<span class="clear_control">[x]</span>'); }
@@ -104,10 +110,10 @@ In injectors and handlers, you have access to the complete faceting widget API (
     var hello_world = function($elem, options) {
       /* declare superclass */
     	var self = repertoire.facet($elem, options);
-	
+
       /* handlers */
-      handler('.hello', function() { 
-        alert('hello, world!'); 
+      handler('.hello', function() {
+        alert('hello, world!');
       });
 
       /* injectors */
@@ -159,12 +165,12 @@ In injectors and handlers, you have access to the complete faceting widget API (
 
 *Q* What Javascript OOP convention is this?
 
-*A* It's based on section 5.4, "Functional Inheritance" of Douglas Crockford, "Javascript: The Good Parts."  
+*A* It's based on section 5.4, "Functional Inheritance" of Douglas Crockford, "Javascript: The Good Parts."
 
 
 *Q* Explain the naming conventions.
 
-*A* $foo is a jquery object, e.g. var $foo = $('.foo') 
+*A* $foo is a jquery object, e.g. var $foo = $('.foo')
 self is the object you're currently defining (as opposed to the one it inherits from, javascript's 'this', or its dom view)
 
 

data/INSTALL

@@ -1,18 +1,17 @@
 === Installing Repertoire Faceting
 
-N.B.  Repertoire Faceting requires Rails 3.0+, Ruby 1.9.2+, and JQuery 1.3.2+.
+N.B.  Repertoire Faceting requires Postgres 9.3+, Rails 3.2+, Ruby 2.0.0+, and JQuery 1.3.2+.
 
-== Short version. 
+== Short version.
 
-(You need a working Rails 3 app, with a model, controller, and a partial to show the model)
+(You need a working Rails app, with a model, controller, and a partial to show the model)
 
   { in Gemfile }
     gem 'repertoire-faceting'                              // 1
 
   { install native bitset extensions }
   $ bundle install
-  $ rake db:faceting:build        { provide sudo your password }
-  $ rake db:faceting:load
+  $ rake db:faceting:extensions:install        { provide sudo your password }
 
   { in ./app/models/some_model.rb }
     class SomeModel
@@ -25,14 +24,14 @@ N.B.  Repertoire Faceting requires Rails 3.0+, Ruby 1.9.2+, and JQuery 1.3.2+.
           include Repertoire::Faceting::Controller         // 4
           def base; return SomeModel; end                  // 5
         end
-        
+
   { in ./config/routes.rb }
     SomeApp::Application.routes.draw do
         faceting_for :some_model                           // 6
       end
-    
+
     { in ./public/javascripts/application.js }
-      //= require <rep.faceting>                           // 7
+      //= require rep.faceting                             // 7
 
   { in ./app/views/some_controller/index.html.erb }
     <script language="javascript">
@@ -49,65 +48,59 @@ N.B.  Repertoire Faceting requires Rails 3.0+, Ruby 1.9.2+, and JQuery 1.3.2+.
 
     ... that's a complete faceted browser in only 13 new lines of code in your app!
 
-  In production, you will want to compress the javascript facet widgets:
-
-  { in ./config/environments/production.rb }
-    config.repertoire_assets.compress = true
-
   Additionally, you may wish to index the facets.  At the console or in a migration:
 
-  SomeModel.update_indexed_facets([:some_column])
+  SomeModel.index_facets([:some_column])
 
-  The faceting subsystem automatically detects available facet indices and uses 
+  The faceting subsystem automatically detects available facet indices and uses
   them when appropriate.
 
 
 == Detailed version.
 
-Start with a working Rails 3 application with a PostgreSQL database.
+Start with a working Rails application with a PostgreSQL database.
 
-    * Require repertoire-faceting in Gemfile.
+    ** Note that the canonical resource for using Repertoire Faceting is the
+       Repertoire Faceting Example application.  If you have questions, you are
+       best served by getting it running and exploring further there. **
 
-      gem 'repertoire-faceting'
 
-    * Make sure you use Rails version 3.0.2+, which adopted Arel 2.0.1.  If necessary
-      you can pull rails, arel, and rack from git.
+    * Require repertoire-faceting in Gemfile.
 
-      gem 'rails', :git => 'git://github.com/rails/rails.git'
-      gem 'arel',  :git => 'git://github.com/rails/arel.git'
-      gem "rack", :git => "git://github.com/rack/rack.git"
+      gem 'repertoire-faceting'
 
     * At the command line, bundle everything into your application:
 
       $ bundle install
 
-    * From your application root, build and install the repertoire-faceting native 
-      extensions to PostgreSQL.  These provide a bitwise signature type used to 
+    * From your application root, build and install the repertoire-faceting native
+      extensions to PostgreSQL.  These provide a bitwise signature type used to
       index and count facets.
 
-      $ rake db:faceting:build     { sudo will prompt you for your password }
+      $ rake db:faceting:extensions:install     { sudo will prompt you for your password }
 
     * Load the extension into your local application database.  This ensures the
       plpgsql language is installed, and loads (or re-loads) the new bitset signature
       type.
 
-      $ createlang plpgsql -U<username> <database>
-      $ rake db:faceting:load
-  
+      $ psql -c "CREATE EXTENSION faceting;" -U<username> <database>
+
       Or, if you prefer to use migrations create one with the following contents:
-        
-            ....   
-            def self.up
-              load_faceting        # unload_faceting is the reverse
-            end
+
+        def self.change
+          reversible do |dir
+            dir.up   { execute('CREATE EXTENSION faceting') }
+            dir.down { execute('DROP EXTENSION faceting CASCADE') }
+          end
+        end
 
       Before proceeding, you can confirm the module is installed as follows.
 
-      $ psql -c "SELECT count('101010101'::signature);" -U<username> <database>
+      $ psql -c "SELECT facet.count('101010101'::facet.signature);" -U<username> <database>
 
-    * Install the faceting mixin in your Rails model and declare a facet on an 
-      existing database column.  (See the README for complete configuration options 
-      for facets.)  
+    * Install the faceting mixin in your Rails model and declare a facet on an
+      existing database column.  (See the README for complete configuration options
+      for facets.)
 
       { ./app/models/painting.rb }
         class Painting
@@ -119,17 +112,17 @@ Start with a working Rails 3 application with a PostgreSQL database.
 
       $ rails c
       > Painting.count(:genre)
-      => {"Impressionist"=>2, "Medieval"=>2} 
+      => {"Impressionist"=>2, "Medieval"=>2}
       > Painting.refine(:genre => 'Impressionist')
-      => [#<Painting id: 1, title: "Moonlight Shimmers", painter: "Monet", genre: "Impressionist">, 
-          #<Painting id: 2, title: "Nude Lunch in Garden", painter: "Manet", genre: "Impressionist">] 
+      => [#<Painting id: 1, title: "Moonlight Shimmers", painter: "Monet", genre: "Impressionist">,
+          #<Painting id: 2, title: "Nude Lunch in Garden", painter: "Manet", genre: "Impressionist">]
 
       Or, with a base query as well:
 
       > Painting.where(["title like ?", 'Moon%']).count(:genre)
-      => {"Impressionist"=>1} 
+      => {"Impressionist"=>1}
 
-    * Add faceting webservices to your controller and define base() to indicate which model to base queries on 
+    * Add faceting webservices to your controller and define base() to indicate which model to base queries on
 
       { ./app/controllers/paintings_controller }
         class PaintingsController
@@ -141,7 +134,7 @@ Start with a working Rails 3 application with a PostgreSQL database.
           end
         end
 
-    * Add faceting routes to your application.  
+    * Add faceting routes to your application.
 
       { ./config/routes.rb }
 
@@ -158,23 +151,9 @@ Start with a working Rails 3 application with a PostgreSQL database.
         paintings_results        /paintings/results(.:format)       {:controller=>"paintings", :action=>"results"}
         ...
 
-    * Load the javascript facet widgets in your main javascript file. The 
-      repertoire-assets subsystem will locate the widgets in your application's
-      rubygems, and load them as appropriate.
-
-      { ./public/javascripts/application.js }
-        ...
-        //= require <rep.faceting>
-        ...
-
-      N.B. Repertoire Faceting widgets are based on JQuery, which is incompatible 
-           with Prototype.  If you have not already done so, you should remove 
-           prototype.js and rails.js from the javascripts directory, and delete the 
-           "<%= javascript_include_tag :defaults %>" line from application.html.erb.
-
-    * Add facet count and result widgets to your HTML page. The facet context div 
-      collects widgets that affect the same query together. (For complete options, 
-      see the README ) 
+    * Add facet count and result widgets to your HTML page. The facet context div
+      collects widgets that affect the same query together. (For complete options,
+      see the README )
 
       { ./app/views/paintings/index.html.erb }
 
@@ -187,55 +166,44 @@ Start with a working Rails 3 application with a PostgreSQL database.
             </script>
           <div id='paintings'>
             <div id='genre' class='facet'></div>
-            <div id='results'></div> 
+            <div id='results'></div>
           </div>
-    
-    * If you don't already have one, create a partial for displaying your model in 
+
+    * If you don't already have one, create a partial for displaying your model in
       results lists.
 
       { ./app/views/paintings/_painting.html.erb }
-    
+
         <div class='painting' style='width:235px; margin-bottom:5px; padding:2px; border:dotted 1px;'>
           <div>Title: <%= painting.title %></div>
             <div>Painter: <%= painting.painter %></div>
             <div>Genre: <%= painting.genre %></div>
         </div>
 
-    * [ Optional ] Configure the repertoire-assets module that loads the javascript 
-      faceting widgets to compress the widget code in production. 
-
-      { ./config/environments/production.rb }
-
-        PaintingsApp::Application.configure do
-          ...
-          config.repertoire_assets.compress = true
-          ...
-        end
-
-    * [ Optional ] Add bitset indexes to some facets on your model.  The module will 
-      automatically use facet indexes when they are available.  Facet indexes scale 
-      out of the box to over a million model items, and require no additional 
+    * [ Optional ] Add bitset indexes to some facets on your model.  The module will
+      automatically use facet indexes when they are available.  Facet indexes scale
+      out of the box to over a million model items, and requires no additional
       configuration.
 
       $ rails generate migration AddFacetIndex
-  
+
       { ./db/migrate/<your date>add_facet_index.rb   }
             class AddFacetIndex < ActiveRecord::Migration
               def self.up
-                Painting.update_indexed_facets([:genre])
+                Painting.index_facets([:genre])
               end
 
               def self.down
-                Painting.update_indexed_facets
+                Painting.index_facets
               end
             end
 
-    * [ Optional ] Periodically update indexes via a crontab task. 
+    * [ Optional ] Periodically update indexes via a crontab task.
 
       { ./lib/tasks/update_facets.rake }
 
       task :reindex => :environment do
-          Painting.update_indexed_facets
+          Painting.index_facets                           # NB this updates whatever indexes already exist
       end
 
       ... And then configure crontab to execute 'rake reindex' at appropriate intervals.

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009-2012 MIT Hyperstudio
+Copyright (c) 2008-2014 MIT Hyperstudio
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation