Commit to push to heroku varbit

db/migrate/20101028165208_install_faceting.rb

@@ -27,7 +27,7 @@ class InstallFaceting < ActiveRecord::Migration
   def self.up
     if Rails.env.production?
       execute('CREATE SCHEMA facet')
-      execute( faceting_api_sql(:bytea, 'facet') )
+      execute( faceting_api_sql(:varbit, 'facet') )
     else
       execute('CREATE EXTENSION faceting')
     end

vendor/gems/repertoire-faceting-0.6.0/.gitignore

@@ -0,0 +1,22 @@
+test_log
+pkg
+pkg/*
+*.log
+log
+!log*.rb
+*/log
+log/*
+*/log/*
+coverage
+.DS_Store
+*.pid
+*.gem
+TAGS
+*.rbc
+*.tmproj
+.#*
+.bundle
+doc/*
+ext/**/*.o
+ext/**/*.so
+ext/*.sql

vendor/gems/repertoire-faceting-0.6.0/FAQ

@@ -0,0 +1,187 @@
+= Repertoire Faceting FAQ
+
+== General questions
+
+*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 of usage.
+
+
+== About facet indexing and the signature SQL type
+
+*Q* What's the scalability of this thing?
+
+*A* Up to about 500,000 items, supposing 6-8 simultaneous facets with domains anywhere from 2-100 values.  In other words, beyond the size of most commonly available datasets.  See the citizens example in the specs directory & example faceting app. It has been tested with up to 1,000,000 items, but this requires unix configuration to give Postgresql lots of shared memory.
+
+
+*Q* My facets are empty.
+
+*A* Make sure the facet indices aren't empty.  Running '<model>.index_facets([])' from the console will drop them all.
+
+
+*Q* Can I facet over multiple models?
+
+*A* Not currently.  However, this may be possible using an ActiveRecord polymorphic relation on the main model.
+
+
+*Q* Why a new native PostgreSQL type?
+
+*A* As of PostgreSQL 9.3, there is a binding of the Repertoire in-database faceting functions based on VARBIT bit strings.
+However, it is many times slower than using the C-language signature type above.
+
+
+== About the ajax faceting widgets
+
+
+*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() 
+     };
+   });
+
+
+*Q* I want to change the default options for all widgets of a given class.
+
+*A* See the syntax for defining jquery plugins - you can alter the defaults for all widgets by reassigning them in your view code.
+
+*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>'); }
+      },
+      handlers: {
+        'click!.clear_control' : function(self) {
+          self.refinements('genre').length = 0;
+          self.state_changed();
+          return false;
+        }
+      }
+    });
+
+The injector adds markup for the control at the specific jquery selector, and the handler receives events on that markup.  Both receive a single argument 'self' for the widget object, and 'this' for the matched DOM element.
+
+Note the syntax used to identify a handler's event and dom element: '<event.namespace>!<target>'.  Both event and namespace are optional - leave them out to register a click handler with a unique namespace.
+
+In injectors and handlers, you have access to the complete faceting widget API (state, refinements, toggle, is_selected, etc.). You can basically build a new widget, if you need to. See the documentation for the faceting_widget class for details.
+
+
+*Q* My additonal control needs to send data back to the webservice too.
+
+*A* You can pre-process the entire context's state before it's sent to the webservice by update():
+
+   var min = 5;
+   $('#genre').facet({
+     injectors:  { ... },
+     handlers:   { ... },
+     pre_update: function(state) { state.minimum = genre_min; }
+   }
+
+
+*Q* How do I subclass an existing widget, so I can reuse my changes repeatedly?
+
+*A* Basically you define a new widget class and move your injectors and handlers (above) into the appropriate places.  See the results widget for the simplest possible example, and nested_facet for a real-world example that extends the default facet widget.  At a bare minimum, you will over-ride the render() method, and possibly the update() method too.  Here is a 'hello world' that extends the default facet count widget:
+
+    var hello_world = function($elem, options) {
+      /* declare superclass */
+    	var self = repertoire.facet($elem, options);
+
+      /* handlers */
+      handler('.hello', function() { 
+        alert('hello, world!'); 
+      });
+
+      /* injectors */
+      var $template_fn = self.render;
+      self.render = function(data) {
+        var $markup = $template_fn(data);
+        $markup.find('.title .controls').append('<div class='hello'>click me!</div');
+        return $markup;
+      }
+
+      return self;
+    }
+
+
+*Q* That's great, but how do I turn it into a jquery plugin I can actually use?
+
+*A* Call the plugin method and assign it to a variable in the jquery prototype.  If provided, the line following sets universal options defaults for the widget.
+
+   $.fn.hello_world = repertoire.plugin(hello_world);
+   $.fn.hello_world.defaults = { ... };       // put default options here
+
+
+*Q* How do these widgets relate to each other?
+
+*A* Here is the class hierarchy:
+
+   facet_widget (abstract)
+      +--- facet
+           +--- nesting_facet
+      +--- results
+
+
+*Q* In my widget or handler, how do I override an event handler from the superclass?
+
+*A* Register another handler to the exact same event and namespace.  E.g. toggling selection for facet value counts in the default facet widget is registered under the jquery event/namespace 'click.toggle_value'.  To over-ride:
+
+    ... [ in widget's constructor function ]
+
+    self.handler('click.toggle_value!.facet .value', function() {
+       ... redefined event handler
+    }
+    ...
+
+
+*Q* My widget needs to send additional data to the webservice, pre-process the state, compute my own query string, or use a different webservice.
+
+*A* You can over-ride self.update() to alter the webservice ajax call or replace it with your own. (a) if sending additional data that affects only the current widget, store it in a private variable and add it in update().  (b) if the additional data affects all other facets, store it in the structure returned by self.state() and make sure the other widgets/webservices can process it correctly.
+
+
+*Q* What Javascript OOP convention is this?
+
+*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') 
+self is the object you're currently defining (as opposed to the one it inherits from, javascript's 'this', or its dom view)
+
+
+*Q* Why not support the metadata jquery plugin?  Why not automatically turn all elements with a 'facet' class into facet widgets?
+
+*A* Possibly.  It needs some thought.

vendor/gems/repertoire-faceting-0.6.0/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+ruby "2.0.0"
+
+gemspec
+

vendor/gems/repertoire-faceting-0.6.0/Gemfile.lock

@@ -0,0 +1,92 @@
+PATH
+  remote: .
+  specs:
+    repertoire-faceting (0.6.0)
+      jquery-rails
+      pg (>= 0.11, < 0.18)
+      rails (>= 3.2.11, < 4.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actionmailer (4.0.3)
+      actionpack (= 4.0.3)
+      mail (~> 2.5.4)
+    actionpack (4.0.3)
+      activesupport (= 4.0.3)
+      builder (~> 3.1.0)
+      erubis (~> 2.7.0)
+      rack (~> 1.5.2)
+      rack-test (~> 0.6.2)
+    activemodel (4.0.3)
+      activesupport (= 4.0.3)
+      builder (~> 3.1.0)
+    activerecord (4.0.3)
+      activemodel (= 4.0.3)
+      activerecord-deprecated_finders (~> 1.0.2)
+      activesupport (= 4.0.3)
+      arel (~> 4.0.0)
+    activerecord-deprecated_finders (1.0.3)
+    activesupport (4.0.3)
+      i18n (~> 0.6, >= 0.6.4)
+      minitest (~> 4.2)
+      multi_json (~> 1.3)
+      thread_safe (~> 0.1)
+      tzinfo (~> 0.3.37)
+    arel (4.0.2)
+    atomic (1.1.14)
+    builder (3.1.4)
+    erubis (2.7.0)
+    hike (1.2.3)
+    i18n (0.6.9)
+    jquery-rails (3.1.0)
+      railties (>= 3.0, < 5.0)
+      thor (>= 0.14, < 2.0)
+    mail (2.5.4)
+      mime-types (~> 1.16)
+      treetop (~> 1.4.8)
+    mime-types (1.25.1)
+    minitest (4.7.5)
+    multi_json (1.8.4)
+    pg (0.17.1)
+    polyglot (0.3.4)
+    rack (1.5.2)
+    rack-test (0.6.2)
+      rack (>= 1.0)
+    rails (4.0.3)
+      actionmailer (= 4.0.3)
+      actionpack (= 4.0.3)
+      activerecord (= 4.0.3)
+      activesupport (= 4.0.3)
+      bundler (>= 1.3.0, < 2.0)
+      railties (= 4.0.3)
+      sprockets-rails (~> 2.0.0)
+    railties (4.0.3)
+      actionpack (= 4.0.3)
+      activesupport (= 4.0.3)
+      rake (>= 0.8.7)
+      thor (>= 0.18.1, < 2.0)
+    rake (10.1.1)
+    sprockets (2.11.0)
+      hike (~> 1.2)
+      multi_json (~> 1.0)
+      rack (~> 1.0)
+      tilt (~> 1.1, != 1.3.0)
+    sprockets-rails (2.0.1)
+      actionpack (>= 3.0)
+      activesupport (>= 3.0)
+      sprockets (~> 2.8)
+    thor (0.18.1)
+    thread_safe (0.1.3)
+      atomic
+    tilt (1.4.1)
+    treetop (1.4.15)
+      polyglot
+      polyglot (>= 0.3.1)
+    tzinfo (0.3.38)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  repertoire-faceting!