Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
116 lines (71 sloc) 6.44 KB

This is an advanced search plugin for Blacklight ( ). It is meant to be installed alongside the Blacklight plugin in your application's vendor/plugins directory.



Clone the advanced search plugin from github into your application's vendor/plugins directory

  • cd into your application's vendor/plugins directory and run the following command:

git clone

You can later use standard git commands to update the plugin to a new version.


from your application's main directory, run:

./script/plugin install

You can later use “./script/plugin update blacklight_advanced_search” to update to latest code.

You may now want to install gem dependencies added by the gem, by running:

sudo rake gems:install

You can also now optionally run the installer script to install some optional example configuration files. In many cases, no configuration is needed for advanced search plugin to work.

  • cd back to your application's root directory

cd ../../
  • And then run the the following command:

rake rails:template LOCATION=vendor/plugins/blacklight_advanced_search/template.rb


The advanced search form will be available in your app at /advanced

url_for(:controller => "advanced", :action => "index")

You can also send the advanced search form url parameters representing a search, to have the form add on additional 'advanced' criteria to the search. Eg:

url_for( params.merge(:controller => "advanced", :action => "index")

By default there won't be any links in your application to the search form, if you've heavily customized your app you can put them wherever you want as above.

However, especially if your app isn't much customized, the optional installer can write a localized Blacklight search form into your application with a 'more options' link to advanced. You may need to adjust your styles to make room for the new link, depending on what you've done with your app.


If your application has it's search fields set up to all use the same Solr qt request handler, then the search plugin may work well with no configuration. However, configuration is available to change or improve behavior.

All plugin configuration mentioned below can be in any initializer in your app (any ruby file in config/initializers), although using the convention config/initializers/blacklight_advanced_search.rb may keep things clear.

The optional installer script can install a sample blacklight_advanced_search.rb for you demonstrating various options.

Search fields ===

Your main blacklight search fields are generally defined in config/blacklight_config.rb, under “config”. A default Blacklight install may give them each a seperate “:qt” parameter, for the Solr request handler they use. If set up like this, they can not be re-used by the advanced search plugin. You can either define fields seperately for the advanced search plugin, or modify your main config so all 'search fields' use the default :qt or share the same :qt.

Additionally, to make your advanced search solr requests more concise, you may want to take advantage of the :local_solr_parameters option in your search field definition to use a solr parameter substitution with $variables.

If there are particular search fields in your main blacklight config you want excluded from the advanced search form, you can set “:include_in_advanced_search => false”

Or, to supply a completely seperate list of search fields for the advanced search form, you can set them yourself, each field is defined by a hash who's format is specified in Blacklight::SearchFields.

BlacklightAdvancedSearch.config[:search_fields] = []
BlacklightAdvancedSearch.config[:search_fields] << {
  :key => :author
  :solr_local_parameters => {

Note that you can't set :qt for search fields for advanced search, they all must share the same Solr request handler (qt).

If you would like the advanced search to use a different Solr request handler than your app's default, set:


to the name of the solr request handler.

Note you can set custom :search_fields while keeping the default :qt, but setting a new :qt requires you to set :search_fields too.


By default, the advanced search form will show as limits whatever facets are configured as default in your Solr request handler. To have the advanced search form request specific facets and/or specific facet parameters, you can set config.

BlacklightAdvancedSearch.config[:form_solr_parameters] = {
  "facet.field" => ["format", "language_facet"],
  "facet.limit" => -1, # return all facet values
  "facet.sort" => "index" # sort by byte order of values

All Config Options


“dismax” or “edismax”. “dismax” is default. “edismax” may work with the edismax query parser, this function may be a work in progress?


Solr request handler to use for any search that includes advanced search criteria. Defaults to what the application has set as Blacklight.config


Key to use in application URLs to indicate advanced search is included in a query, defaults to “advanced”. URLs will have “&search_field=[url key]”.


Array of search field definitions to be used for advanced search. Each element in the array is a hash of the form required by Blacklight::SearchFields. If left blank, the plugin will use definitions from your main app Blacklight.config – only those which have no :qt set, and do not have :include_in_advanced_search => false.


A hash of solr parameters which will be included in Solr request sent before display of advanced search form. Can be used to set facet parameters for advanced search form display.

To Do

  • Fix rspec tests (do not currently pass, have not been updated to new code)

  • Fix to-dismax parser to not choke on quoted phrases in input.

  • Alphabetical sorting of facet values returned by solr in count order (perhaps with limit).