This is an advanced search plugin for Blacklight ( http://www.projectblacklight.org ).  

== Pre-requisites:
* The Blacklight plugin ( http://github.com/projectblacklight/blacklight )
  * NOTE: Blacklight 3.2 is required for current version of Advanced Search plugin
  * 1.1.x versions will work with older version of Blacklight 3.x
  * advanced search plugin latest 0.X.X version will work with Blacklight 2.9/Rails2. 
  * Older tagged versions of Advanced Search may work with even older BL. 

== Installation:

=== Blacklight 3.x/Rails 3

Add to your application's Gemfile:
   gem "blacklight_advanced_search"

then run 'bundle install'.  Then run:
   rails generate blacklight_advanced_search

* The 'generate' command will install the plugin's assets into your application's application.js/application.css asset pipeline files
* It will also generate AdvancedController into app/controllers/advanced_controller.rb, which you should configure for your local needs.
* And it can optionally install a localized search form with a link to advanced search. If you've already localized your search form you'll want to do this manually instead. 

You may want to set `blacklight_config.advanced_search.advanced_parse_q = true` to enable AND/OR/NOT parsing even in ordinary search, this is not on by default.  

== Accessing
 
 
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.  For example:

  url_for( params.merge(:controller => "advanced", :action => "index")
  
If you do not have the default :controller/:action route enabled for your application, you may need to add a custom route to config/routes.rb.  For example:

    map.advanced 'advanced', :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. 



== Configuration:

If your application uses a single Solr qt request handler for all its search fields, then this plugin may work well with no configuration.  Nonetheless, configuration is available to change or improve behavior, or to use a separate Solr request handler for the advanced search plugin.

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 which demonstrates various options.

=== Expression parsing in ordinary search

If you turn on this feature with `blacklight_config.advanced_search.advanced_parse_q = true`, then the plugin will intercept queries entered in ordinary Blacklight search interface, and parse them for AND/OR/NOT (and parens), producing appropriate Solr query. This allows single-field boolean expressions to be entered in ordinary search, providing a consistent experience with advanced search. 

When this feature is turned on, queries that don't have any special operators (eg: AND, OR, NOT, parens) will still be passed to Solr much the same as they were before. But queries with special operators will have appropriate Solr queries generated for them, usually including nested "_query_" elements, to have the same meaning they would in advanced search. If a user enters something that is a syntax error for parsed search (for instance an unclosed phrase quote or paren), the logic will rescue from the parse erorr by running the exact user entered query direct to solr without advanced parsing. 

Due to limitations of the logic, sometimes these generated Solr queries may not really be as simple as they could be, they may include a *single* nested _query_, which really doens't need to be a nested query at all, although it will still work fine. 

=== Search fields

Your main blacklight search fields are generally defined in config/blacklight_config.rb, under "config[:search_fields]" ( https://github.com/projectblacklight/blacklight/blob/master/config/initializers/blacklight_config.rb#L194 ). 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"

All advanced search fields must share the same Solr request handler (":qt"). As such, search fields that use a custom ":qt" parameter may not be re-used by the advanced search plugin. However, you may use a separate Solr request handler than the Blacklight default. If you would like the advanced search to use a different Solr request handler than your app's default, set:
  blacklight_config.advanced_search.qt
to the name of the Solr request handler. 

If you use a separate Solr request handler for advanced search, you must supply a completely separate list of search fields for the advanced search form. Each field is defined by a hash whose format is specified in Blacklight::SearchFields ( https://github.com/projectblacklight/blacklight/blob/master/lib/blacklight/search_fields.rb#L7 ). 

  blacklight_config.search_fields.empty

  blacklight_config.add_search_field('title') do |field|
    field.solr_local_parameters => {
      :qf => "title_t subtitle_t addl_titles_t title_unstem_search^1000" # see ( http://wiki.apache.org/solr/DisMaxQParserPlugin#qf_.28Query_Fields.29 )
      :pf => "title_t subtitle_t addl_titles_t title_unstem_search^1000" # see ( http://wiki.apache.org/solr/DisMaxQParserPlugin#pf_.28Phrase_Fields.29 )
    }
  end

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

  blacklight_config.add_search_field('authot') do |field|
    field.solr_local_parameters => {
      :qf=>"$qf_author",
      :pf=>"$pf_author"
    }
  end

Within your solrconfig.xml you may then provide the appropriate custom configuration.

  <requestHandler name="advanced" class="solr.SearchHandler" >
    <lst name="defaults">
      <!-- ... -->
      <str name="qf_author">
        author_1xx_unstem_search^200
        author_7xx_unstem_search^50
        author_8xx_unstem_search^10
        author_1xx_search^20       vern_author_1xx_search^20
        author_7xx_search^5        vern_author_7xx_search^5
        author_8xx_search          vern_author_8xx_search
      </str>
      <str name="pf_author">
        author_1xx_unstem_search^5000
        author_7xx_unstem_search^3000
        author_1xx_search^500        vern_author_1xx_search^500
        author_7xx_search^300        vern_author_7xx_search^300
        author_8xx_unstem_search^250
        author_8xx_search^200        vern_author_8xx_search^200
      </str>
    </lst>
  </requestHandler>


=== Facets

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[:form_solr_parameters]. 

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

=== Advanced Search Config Options

[:qt] 
   Solr request handler to use for any search that includes advanced search criteria. Defaults to what the application has set as Blacklight.config[:default_qt]
[:url_key]
   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]".
[:form_solr_paramters]
  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.  
[:advanced_parse_q]
  Set to 'true' to have AND/OR/NOT parsed even in ordinary 'simple' blacklight search, and converted to appropriate Solr query for that single field. 

== Translation to Solr Query, technical details

The code for mapping a user-entered query to a Solr query is called "nesting_parsing", and maps to a 'lucene' query parser query, with nested 'dismax' query parser queries. 

Some technical details can be found in the nesting_parsing README: [https://github.com/projectblacklight/blacklight_advanced_search/tree/master/lib/parsing_nesting]

You may also find the rspecs for parsing a user-entered query and converting it to Solr illumnating:
1. Converting user-entered query to Solr: [https://github.com/projectblacklight/blacklight_advanced_search/blob/master/spec/parsing_nesting/to_solr_spec.rb]
2. Parsing user-entered query to internal syntax tree: [https://github.com/projectblacklight/blacklight_advanced_search/blob/master/spec/parsing_nesting/build_tree_spec.rb]
 
== Running tests

Test coverage is provided with rspec, run all tests by running:
   spec ./spec 

  
== To Do

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