Browse files

README polish, with new js dependencies section

  • Loading branch information...
1 parent 7c82893 commit 6f9d5b6679b122212599fc0bac3d026ad63f8b14 @jrochkind jrochkind committed Mar 27, 2012
Showing with 23 additions and 9 deletions.
  1. +23 −9 README.rdoc
View
32 README.rdoc
@@ -23,7 +23,7 @@ The pre Solr 1.4 now deprecated sint or slong types should work fine too.
= Installation
-== Blacklight 3.x/Rails 3.x
+Recent versions of this plugin require Blacklight versions 3.2 or later, which requires Rails 3.1 or later and the Rails asset pipeline.
Add
@@ -37,8 +37,6 @@ Then run
This will install some asset references in your application.js and application.css.
-**Note** that blacklight_range_limit js will 'require' jquery into your manifest even if you didn't already have it, the JS needs jquery.
-
= Configuration
You have at least one solr field you want to display as a range limit, that's why you've installed this plugin. In your CatalogController, the facet configuration should look like:
@@ -47,7 +45,6 @@ You have at least one solr field you want to display as a range limit, that's wh
You should now get range limit display. More complicated configuration is available if desired, see Range Facet Configuration below.
-Note that the plugin will be default inject links to the Flot JQuery plugin, and a couple dependencies. The weird way it has to do this may fail in weird configurations. You can turn this off and instead include Flot and its dependencies manually in your application, see Injection below.
You can also configure the look and feel of the Flot chart using the jQuery .data() method. On the `.facet_limit` container you want to configure, add a Flot options associative array (documented at http://people.iola.dk/olau/flot/API.txt) as the `plot-config` key. The `plot-config` key to set the `plot-config` key on the appropriate `.facet_limit` container. In order to customize the plot colors, for example, you could use this code:
@@ -78,18 +75,33 @@ Note that a drill-down will never require the second request, because boundaries
Instead of simply passing "true", you can pass a hash with additional configuration. Here's an example with all the available keys, you don't need to use them all, just the ones you want to set to non-default values.
-config.add_facet_field 'pub_date', :label => 'Publication Year', :range => {
- :num_segments => 6,
- :assumed_boundaries => [1100, Time.now.year + 2],
- :segments => false
- }
+ config.add_facet_field 'pub_date', :label => 'Publication Year', :range => {
+ :num_segments => 6,
+ :assumed_boundaries => [1100, Time.now.year + 2],
+ :segments => false
+ }
[num_segments]
Default 10. Approximately how many segments to divide the range into for segment facets, which become segments on the chart. Actual segments are calculated to be 'nice' values, so may not exactly match your setting.
[assumed_boundaries]
Default null. For a result set that has not yet been limited, instead of taking boundaries from results and making a second AJAX request to fetch segments, just assume these given boundaries. If you'd like to avoid this second AJAX Solr call, you can set :assumed_boundaries to a two-element array of integers instead, and the assumed boundaries will always be used. Note this is live ruby code, you can put calculations in there like Time.now.year + 2.
[:segments]
Default true. If set to false, then distribution segment facets will not be loaded at all.
+
+== Javascript dependencies
+
+The selectable histograms/barcharts are done with Javascript, using Flot[http://code.google.com/p/flot/]. Flot requires JQuery, as well as support for the HTML5 canvas element. In IE previous to IE9, canvas element support is added with excanvas[http://excanvas.sourceforge.net/].
+
+A `require 'blacklight_range_limit'` in a Rails asset pipeline manifest file will automatically include all of these things. The blacklight_range_limit adds just this line to your `app/assets/application.js`.
+
+There is a copy of flot vendored in this gem for this purpose. jquery is obtained from the jquery-rails gem, which this gem depends on.
+
+Note this means a copy of jquery, from the jquery-rails gem, will be included in your assets by blacklight_range_limit even if you didn't include it yourself explicitly in application.js. Flot will also be included.
+
+If you don't want any of this gem's JS, you can simply remove the `require 'blacklight_range_limit'` line from your application.js, and hack something else together yourself.
+
+The excanvas inclusion for IE is handled a bit differently. Coudln't get conditional inclusion of excanvas in pure JS to work, it does need an actual seperate script line in the HTML document surrounded by IE conditional comments; this gem adds that line using Blacklight's `extra_head_content` feature allowing dependencies to inject content in HTML head; requires your layout to follow BL conventions, or just add excanvas yourself manually. This gem's attempt to inject the excanvas script line can be turned off in configuration, see Injection below.
+
== Injection
@@ -120,6 +132,8 @@ You can also turn off injection of individual components, which could be more us
[:excanvas]
Disables injection of a conditionally-commented script tag to load the excanvas library for supporting 'canvas' on IE. blacklight_range_limit does this in the controller mixin, using Blacklight's "extra_head_content" feature to add actual conditional script tag for IE in html <head>.
+See Javascript Dependencies above for disabling injection of gem's js.
+
= Tests
Start the Blacklight demo jetty server (on port 8983)

0 comments on commit 6f9d5b6

Please sign in to comment.