repertoire-faceting 0.5

data/FAQ

@@ -0,0 +1,161 @@
+= Repertoire Faceting FAQ =
+
+= 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 nested facet widget is empty!
+
+A. Did you remember to call expand_nesting(<facet index table>, <facet name>) after creating your index?
+
+
+
+= About the ajax faceting widgets =
+
+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's 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.  (1) if sending additional 
+   data that affects only the current widget, store it in a private variable and add it in update().  (2) if the additional 
+   data affects all otherfacets, 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.

data/INSTALL

@@ -0,0 +1,7 @@
+== Installing Repertoire Faceting
+
+Start with a working Rails 3 application with a PostgreSQL database.
+
+* require repertoire-faceting in Gemfile:
+
+  

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2009-2010 MIT Hyperstudio
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.