repertoire-faceting 0.5.5 → 0.6.0

data/lib/assets/javascripts/rep.widgets/model.js

@@ -0,0 +1,159 @@
+/*
+* Repertoire abstract ajax model, for use with widget framework
+*
+* Copyright (c) 2009 MIT Hyperstudio
+* Christopher York, 11/2009
+*
+* Requires jquery 1.3.2+
+* Support: Firefox 3+ & Safari 4+.  IE emphatically not supported.
+*/
+
+//
+// Abstract model for ajax widgets.  This class includes convenience methods for listening to
+// events on models, for jquery ajax calls, and for param encoding in Merb's style.
+//
+// Handles:
+//       - change publication and observing
+//       - url/query-string construction
+//
+// Usage. The model provides a facade to your ajax webservice, and may hold state for a widget.
+//        In some cases (e.g. working with large server-side datasets), it may be appropriate to
+//        cache data in the model and fetch it as needed from the webservice.
+//
+// Using the ajax param encoders.  These convenience methods help you construct the url and
+//        assemble params for an ajax call.  It's not required to use them, although they make life
+//        easier.
+//
+// self.items = function(callback) {
+//   var url = self.default_url(['projects', 'results']);
+//   self.fetch(params, url, 'html', callback);
+// }
+//
+repertoire.model = function(options) {
+  // this object is an abstract class
+  var self = {};
+  
+  // default: no options specified
+  options = options || {};
+  
+  // mixin event handler functionality
+  repertoire.events(self);
+  
+  //
+  // Update the data model given the current state
+  //
+  // You may either pre-process the state and write your own webservice access methods
+  // or use self.fetch for a generic webservice, e.g.
+  //
+  // self.update = function(state, callback) {
+  //   var url = self.default_url(['projects', 'results']);
+  //   self.fetch(state, url, 'html', callback);
+  // }
+  //
+  self.update = function(state, callback) {
+    throw "Abstract function: redefine self.update() in your data model."
+  };
+  
+  //
+  // Utility method to issue an ajax HTTP GET to fetch data from a webservice
+  //
+  //   params:   params to send as http query line
+  //   url:      url of webservice to access
+  //   type:     type of data returned (e.g. 'json', 'html')
+  //   callback: function to call with returned data
+  //
+  self.fetch = function(params, url, type, callback, $elem, async) {
+    if (async == null)
+      async = true;
+
+    var spinnerClass = options.spinner || 'loading';
+    if ($elem)
+      $elem.addClass(spinnerClass);
+    $.ajax({
+      async:    async,
+      url:      url,
+      data:     self.to_query_string(params),
+      type:     'GET',
+      dataType: type,
+      // content negotiation problems may require:
+      /* beforeSend: function(xhr) { xhr.setRequestHeader("Accept", "application/json") } */
+      success:  callback,
+      error:    function(request, textStatus, errorThrown) {
+          if ($elem)
+            $elem.html(options.error || 'Could not load');
+      },
+      complete: function () {
+          if ($elem)
+            $elem.removeClass(spinnerClass);
+      }
+    });
+  };
+  
+  //
+  // Format a webservice url, preferring options.url if possible
+  //
+  self.default_url = function(default_parts, ext) {
+    var path_prefix = options.path_prefix || '';
+    var parts       = default_parts.slice();
+
+    parts.unshift(path_prefix);
+    url = options.url || parts.join('/')
+
+    if (ext)
+      url += '.' + ext;
+
+    return url;
+  }
+  
+  //
+  // Convert a structure of params to a URL query string suitable for use in an HTTP GET request, compliant with Merb's format.
+  //
+  //   An example:
+  //
+  //   Merb::Parse.params_to_query_string(:filter => {:year => [1593, 1597], :genre => ['Tragedy', 'Comedy'] }, :search => 'William')
+  //   ==> "filter[genre][]=Tragedy&filter[genre][]=Comedy&filter[year][]=1593&filter[year][]=1597&search=William"
+  //
+  self.to_query_string = function(value, prefix) {
+    var vs = [];
+    prefix = prefix || '';
+    if (value instanceof Array) {
+      jQuery.each(value, function(i, v) {
+        vs.push(self.to_query_string(v, prefix + '[]'));
+      });
+      return vs.join('&');
+    } else if (typeof(value) == "object") {
+      jQuery.each(value, function(k, v) {
+        vs.push(self.to_query_string(v, (prefix.length > 0) ? (prefix + '[' + encodeURIComponent(k) + ']') : encodeURIComponent(k)));
+      });
+      // minor addition to merb: discard empty value lists { e.g. discipline: [] }
+      vs = array_filter(vs, function(x) { return x !== ""; });
+      return vs.join('&');
+    } else {
+      return prefix + '=' + encodeURIComponent(value);
+    }
+  };
+
+  // Apparently IE doesn't support the filter function? -DD via Brett
+  var array_filter = function (thisArray, fun) {
+    var len = thisArray.length;
+      if (typeof fun != "function")
+        throw new TypeError();
+
+      var res = new Array();
+      var thisp = arguments[1];
+
+      for (var i = 0; i < len; i++) {
+        if (i in thisArray) {
+          var val = thisArray[i]; // in case fun mutates this
+          if (fun.call(thisp, val, i, thisArray)) 
+            res.push(val);
+	}
+      }
+
+      return res;
+  };
+
+    
+  // end of model factory function
+  return self;
+}

data/lib/assets/javascripts/rep.widgets/widget.js

@@ -0,0 +1,213 @@
+/*
+* Repertoire abstract ajax widget
+*
+* Copyright (c) 2009 MIT Hyperstudio
+* Christopher York, 09/2009
+*
+* Requires jquery 1.3.2+
+* Support: Firefox 3+ & Safari 4+.  IE emphatically not supported.
+*/
+
+//
+// Abstract class for ajax widgets
+//
+// Handles:
+//       - url/query-string construction
+//       - data assembly for sending to webservice
+//       - ui event delegation hooks
+//       - hooks for injecting custom behaviour
+//
+// Options on all subclassed widgets:
+//
+//   url         - provide a url to over-ride the widget's default
+//   spinner     - css class to add to widget during ajax loads
+//   error       - text to display if ajax load fails
+//   injectors   - additional jquery markup to inject into widget (see FAQ)
+//   handlers    - additional jquery event handlers to add to widget (see FAQ)
+//   state  - additional pre-processing for params sent to webservice (see FAQ)
+//
+// Sub-classes are required to over-ride one method: self.render().  If you wish to
+// use a data model, store a subclass of rep.wigets/model in your widget.
+//
+repertoire.widget = function(selector, options) {
+  // this object is an abstract class
+  var self    = {};
+  
+  // private variables
+  var $widget = $(selector);
+  options     = options || {};
+  
+  // mix in event handling functionality
+  repertoire.events(self, $widget);
+
+  // to run by hand after sub-classes have evaluated
+  self.initialize = function() {
+    // register any custom handlers
+    if (options.handlers !== undefined)
+      register_handlers(options.handlers);
+      
+    // load once at beginning
+    self.refresh();
+  }
+
+  //
+  // Refresh model and render into widget
+  //
+  // Integrates state and markup injectors
+  //
+  self.refresh = function() {
+    var callback;
+    
+    // pass to custom state processor
+    if (options.state !== undefined)
+      options.state(self);
+      
+    callback = function() {
+      // render the widget
+      var markup = self.render.apply(self, arguments);
+      
+      // inject any custom markup
+      if (options.injectors !== undefined)
+        // TODO.  figure out how to send all args to injectors
+        process_injectors(markup, options.injectors, arguments[0]);
+
+      // paint markup into the dom
+      if (markup)
+        $widget.html(markup);
+    };
+
+    // start rendering
+    self.reload(callback);
+  };
+
+  //
+  // Render and return markup for this widget.
+  //
+  // Three forms are possible:
+  //
+  // (1) Basic... just return a string or jquery object
+  //
+  //     self.render = function() {
+  //       return 'Hello world!';
+  //     };
+  //
+  // (2) If you just want to tweak the superclass' view:
+  // 
+  //     var template_fn = self.render;            // idiom to access super.render()
+  //     self.render = function() {
+  //       var markup = template_fn();
+  //       return $(markup).find('.title').html('New Title');
+  //     };
+  //
+  // (3) If you want to modify the DOM in place, do so
+  //     and return nothing.
+  //
+  self.render = function() {
+    return $('<div class="rep"/>');      // namespace for all other widget css is 'rep'
+  };
+  
+  
+  //
+  // A hook for use when your widget must render the results of an ajax callback.  Put
+  // the ajax call in self.reload().  Its results will be passed to self.render().
+  //
+  // self.reload = function(callback) {
+  //   $.get('http://www.nytimes.com', callback);
+  // };
+  //
+  // self.render = function(daily_news) {
+  //   $(daily_news).find('title').text();   // widget's view is the title of the new york times
+  // }
+  //
+  // N.B. In real-world cases, the call in self.reload should be to your
+  //      data model class, which serves as an ajax api facade.
+  //
+  self.reload = function(callback) {
+    callback();
+  }
+
+  //
+  // Register a handler for dom events on this widget.  Call with an event selector and a standard jquery event
+  // handler function, e.g.
+  //
+  //    self.handler('click.toggle_value!.rep .facet .value', function() { ... });
+  //
+  // Note the syntax used to identify a handler's event, namespace, and the jquery selector: '<event.namespace>!<target>'.
+  // Both event and namespace are optional - leave them out to register a click handler with a unique namespace.
+  //
+  // N.B. This method is intended only for protected use within a widget and its subclasses, since it depends
+  //      on the view implementation.
+  //
+  self.handler = function(event_selector, fn) {
+    event_selector = parse_event_selector(event_selector);
+    var event    = event_selector[0],
+        selector = event_selector[1];  // why doesn't JS support array decomposition?!?
+      
+    // bind new handler
+    $widget.bind(event, function (e) {
+      var $el = $(e.target);
+      var result = false;
+      // walk up dom tree for selector
+      while ($el.length > 0) {
+        if ($el.is(selector)) {
+          result = fn.apply($el[0], [e]);
+          if (result === false)
+            e.preventDefault();
+          return;
+        }
+        $el = $el.parent();
+      }
+    });
+  }
+  
+  // PRIVATE
+  
+  // register a collection of event handlers
+  function register_handlers(handlers) {
+    $.each(handlers, function(selector, handler) {
+      // register each handler
+      self.handler(selector, function() {
+        // bind self as an argument for the custom handler
+        return handler.apply(this, [self]);
+      });
+    });
+  }
+
+  // inject custom markup into widget
+  function process_injectors($markup, injectors, data) {
+    // workaround for jquery find not matching top element
+    $wrapped = $("<div/>").append($markup);
+
+    $.each(injectors, function(selector, injector) {
+      var $elems = $wrapped.find(selector);
+      if ($elems.length > 0) {
+        injector.apply($elems, [ self, data ]);
+      }
+    });
+  }
+  
+  // parse an event name and selector spec
+  function parse_event_selector(event_selector) {
+    var s = event_selector.split('!');
+    var event, selector;
+
+    if (s.length === 2) {
+      event = s[0], selector = s[1];
+    } else if (s.length === 1) {
+      event = 'click', selector = s[0];
+    } else {
+      throw "Could not parse event selector: " + event_selector;
+    }
+
+    if (event.indexOf('.')<0) {
+      // create a default namespace from selector or random number
+      namespace = selector.replace(/[^a-zA-z0-9]/g, '') || new Date().getTime();
+      event = event + '.' + namespace;
+    }
+
+    return [event, selector];
+  }
+
+  // end of widget factory function
+  return self;
+};

data/lib/assets/javascripts/rep.widgets.js

@@ -0,0 +1,14 @@
+/*
+* Repertoire abstract ajax widget
+*
+* Copyright (c) 2009 MIT Hyperstudio
+* Christopher York, 09/2009
+*
+* Requires jquery 1.3.2+
+* Support: Firefox 3+ & Safari 4+.  IE emphatically not supported.
+*/
+
+//= require rep.widgets/global
+//= require rep.widgets/widget
+//= require rep.widgets/events
+//= require rep.widgets/model

data/{public → lib/assets}/stylesheets/rep.faceting.css

@@ -14,5 +14,5 @@
 .rep .facet .values .value .label { position: relative; left: 0.5em;}
 .rep .facet .values .value .label:hover,
 .rep .facet .nesting_level:hover  { cursor: pointer; text-decoration: underline; }
-.loading .spinner                 { background: url(../images/repertoire-faceting/spinner_sm.gif) no-repeat left center; float:right; min-height:15px; min-width:15px;}
+.loading .spinner                 { background: url(/assets/repertoire-faceting/spinner_sm.gif) no-repeat left center; float:right; min-height:15px; min-width:15px;}
 .loading .mask                    { background: rgba(255, 255, 255, 0.6); position:absolute; top:0; left:0; width: 100%; height: 100%; }

data/lib/repertoire-faceting/adapters/postgresql_adapter.rb

@@ -3,7 +3,7 @@ require 'active_support/ordered_hash'
 module Repertoire
   module Faceting
     module PostgreSQLColumn #:nodoc:
-          
+
       # TODO.  still not clear how ActiveRecord adapters support adding custom SQL data types...
       #        feels like a monkey-patch, but there's no documented way to accomplish this simple task
       def simplified_type(field_type)
@@ -12,82 +12,141 @@ module Repertoire
         when 'signature'
           :string
         else
-          super        
+          super
         end
       end
-      
+
     end
-    
+
     module PostgreSQLAdapter #:nodoc:
-      
-      # Creates (or recreates) the packed id column on a given table
-      def renumber_table(table_name, faceting_id, wastage)
-        sql = "SELECT renumber_table('#{table_name}', '#{faceting_id}', #{wastage})"
-        execute(sql)
+
+      #
+      # Methods for accessing faceting APIs (as PostgreSQL extensions)
+      #
+
+      # Returns the available in-database faceting APIs (only when installed as an extension)
+      def facet_api_bindings
+        @api_bindings ||= select_values "SELECT name FROM pg_available_extensions WHERE name LIKE 'faceting%'"
       end
 
-      # Returns the scatter quotient of the given id column
-      def signature_wastage(table_name, faceting_id)
-        sql    = "SELECT signature_wastage('#{table_name}', '#{faceting_id}')"
-        result = select_value(sql)
-        Float(result)
+      # Returns the currently active faceting API binding (only when installed as an extension)
+      def current_facet_api_binding
+        @current_api_binding ||= select_value "SELECT extname FROM pg_extension WHERE extname LIKE 'faceting%';"
       end
-      
-      # Creates (recreates) a table with the specified select statement
-      def recreate_table(table_name, sql)
-        sql = "SELECT recreate_table('#{table_name}', $$#{sql}$$)"
-        execute(sql)
+
+      #
+      # Methods for access to facet indices
+      #
+
+      def facet_schema
+        # TODO. Not clear how to get the schema associated with a PostgreSQL extension from the
+        #       system tables. So we limit to loading into a schema named 'facet' for now.
+        'facet'
       end
-      
-      # Load PostgreSQL native bitset type into current database
-      def load_faceting
-        sql = File.read(Repertoire::Faceting::MODULE_PATH + '/ext/signature.sql')
-        unload_faceting
-        execute(sql)
+
+      def facet_table_name(model_name, name)
+        "#{facet_schema}.#{model_name}_#{name}_index"
       end
-      
-      # Unloads PostgreSQL native bitset type
-      def unload_faceting
-        execute("DROP TYPE IF EXISTS signature CASCADE")
+
+      def indexed_facets(model_name)
+        sql = "SELECT matviewname FROM pg_matviews WHERE schemaname = 'facet'"
+        tables = select_values(sql)
+
+        tables.grep(/#{model_name}_(\w+)_(\d*)?index/) { $1 }
       end
-      
-      # Expands nested faceting for the specified table (once)
-      def expand_nesting(table_name)
-        sql = "SELECT expand_nesting('#{table_name}')"
-        execute(sql)
+
+      #
+      # Methods for managing packed id columns on models
+      #
+
+      def signature_wastage(table_name, faceting_id)
+        sql = "SELECT #{facet_schema}.wastage(#{faceting_id}) FROM #{table_name}"
+        result = select_value(sql)
+        Float(result)
       end
-      
+
+      #
+      # Methods for running facet value counts
+      #
+
       def population(facet, masks, signatures)
         # Would be nice to use Arel here... but recent versions (~ 2.0.1) have removed the property of closure under
         # composition (e.g. joining two select managers / sub-selects)... why?!?
-        sigs  = [ 'facet.signature' ]
+        sigs  = [ 'fct.signature' ]
         exprs = masks.map{|mask| "(#{mask.to_sql})"}
         sigs << 'mask.signature' unless masks.empty?
-        
-        sql  = "SELECT facet.#{facet.facet_name}, count(#{ sigs.join(' & ')}) "
-        sql += "FROM (#{signatures.to_sql}) AS facet "
-        sql += ", (SELECT (#{exprs.join(' & ')}) AS signature) AS mask " unless masks.empty?
+
+        bit_and = " OPERATOR(#{facet_schema}.&) "
+
+        sql  = "SELECT fct.#{facet.facet_name}, #{facet_schema}.count(#{ sigs.join(bit_and) }) "
+        sql += "FROM (#{signatures.to_sql}) AS fct "
+        sql += ", (SELECT (#{exprs.join(bit_and)}) AS signature) AS mask " unless masks.empty?
         sql += "ORDER BY #{facet.order_values.join(', ')} " if facet.order_values.present?
         sql += "OFFSET #{facet.offset_value} "              if facet.offset_value.present?
         sql += "LIMIT #{facet.limit_value} "                if facet.limit_value.present?
-        
+
         # run query and type cast
         results = query(sql)
         results = results.map { |key, count| [ key, count.to_i] }
         results = ActiveSupport::OrderedHash[results]
-        
+
         # minimums and nils
-        results = results.reject { |key, count| count < (facet.minimum_value || 1) }
-        results.delete(nil)                           if facet.nils_value == false
-        
+        results.reject! { |key, count| count < (facet.minimum_value || 1) }
+        results.delete(nil)            if facet.nils_value == :exclude
+
         results
       end
-      
+
       def mask_members_sql(masks, table_name, faceting_id)
+        bit_and = " OPERATOR(#{facet_schema}.&) "
         exprs = masks.map { |mask| "(#{mask.to_sql})" }
-        "INNER JOIN members(#{exprs.join(' & ')}) AS _refinements_id ON (#{table_name}.#{faceting_id} = _refinements_id)"
+        "INNER JOIN #{facet_schema}.members(#{exprs.join(bit_and)}) AS _refinements_id ON (#{table_name}.#{faceting_id} = _refinements_id)"
       end
-      
+
+
+      module MigrationMethods #:nodoc:
+
+        #
+        # Methods used in creating, updating, and removing facet indices
+        #
+
+        def create_materialized_view(view_name, sql)
+          sql = "CREATE MATERIALIZED VIEW #{quote_table_name(view_name)} AS #{sql}"
+          execute(sql)
+        end
+
+        def refresh_materialized_view(view_name)
+          sql = "REFRESH MATERIALIZED VIEW #{quote_table_name(view_name)}"
+          execute(sql)
+        end
+
+        def drop_materialized_view(view_name)
+          sql = "DROP MATERIALIZED VIEW #{quote_table_name(view_name)} CASCADE"
+          execute(sql)
+        end
+
+        # Returns the named PostgreSQL API binding sql; for shared hosts where you cannot build extensions
+        def faceting_api_sql(api_name, schema_name)
+          path        = Repertoire::Faceting::MODULE_PATH
+          version     = Repertoire::Faceting::VERSION
+          api_name    = api_name.to_sym
+          file_name   = "#{path}/ext/faceting_#{api_name}--#{version}.sql"
+
+          raise "Use 'CREATE EXTENSION faceting' to load the default facet api"        if api_name == :signature
+          raise "Currently, the faceting API must install into a schema named 'facet'" unless schema_name == facet_schema
+
+          # TODO This approach allows production deploys to skip a "rake db:extensions:install" step when installing
+          #      to Heroku. In practice, this eases deployment significantly. But shelling out to make during a
+          #      Rails migration feels inelegant.
+          system "cd #{path}/ext; make"                    unless File.exist?(file_name)
+          raise "No API binding available for #{api_name}" unless File.exist?(file_name)
+
+          File.read(file_name).gsub(/@extschema@/, facet_schema)
+        end
+      end
+
+      include MigrationMethods
+
     end
   end
 end