{"id":18517748,"url":"https://github.com/projectblacklight/blacklight_advanced_search","last_synced_at":"2025-04-09T08:31:06.329Z","repository":{"id":39706647,"uuid":"638879","full_name":"projectblacklight/blacklight_advanced_search","owner":"projectblacklight","description":"Advanced search plugin for Blacklight","archived":false,"fork":false,"pushed_at":"2023-06-02T15:44:19.000Z","size":578,"stargazers_count":24,"open_issues_count":28,"forks_count":25,"subscribers_count":15,"default_branch":"main","last_synced_at":"2024-03-25T22:23:44.505Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://projectblacklight.org","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/projectblacklight.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2010-04-29T21:02:31.000Z","updated_at":"2023-11-16T22:35:53.000Z","dependencies_parsed_at":"2023-02-18T01:15:46.812Z","dependency_job_id":null,"html_url":"https://github.com/projectblacklight/blacklight_advanced_search","commit_stats":null,"previous_names":[],"tags_count":52,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectblacklight%2Fblacklight_advanced_search","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectblacklight%2Fblacklight_advanced_search/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectblacklight%2Fblacklight_advanced_search/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectblacklight%2Fblacklight_advanced_search/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/projectblacklight","download_url":"https://codeload.github.com/projectblacklight/blacklight_advanced_search/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223381994,"owners_count":17136292,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T17:08:25.117Z","updated_at":"2024-11-06T17:08:27.578Z","avatar_url":"https://github.com/projectblacklight.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"This is an advanced search plugin for Blacklight ( http://www.projectblacklight.org ).\n\n[![Gem Version](https://badge.fury.io/rb/blacklight_advanced_search.svg)](http://badge.fury.io/rb/blacklight_advanced_search)  [![Build Status](https://travis-ci.org/projectblacklight/blacklight_advanced_search.svg)](https://travis-ci.org/projectblacklight/blacklight_advanced_search)\n\n## Blacklight version compatibility\n\nThis is a plugin for [Blacklight](http://github.com/projectblacklight/blacklight)\n\nIt has been hard to keep track of which versions of `blacklight_advanced_search`\nwork with which versions of `blacklight`. Some notes:\n\n* versions 5.x of Advanced Search plugin should work with Blacklight \u003e= 5.1 and \u003c 6 -- we now synchronize the _major_ version number between `blacklight` and `blacklight_advanced_search`.\n  * `blacklight_advanced_search` 5.x changes the URL query param format for advanced 'inclusive'\n     facet selections, from the advanced form. If you'd like to keep old-style possibly\n     bookmarked URLs working, by redirecting to new format, add this to your\n     `CatalogController`:\n\n            before_filter BlacklightAdvancedSearch::RedirectLegacyParamsFilter, :only =\u003e :index\n\n* version 2.2 of `blacklight_advanced_search` should work with `blacklight` 4.x.\n* versions `1.2.*` of Advanced Search plugin can work with blacklight 3.2.2 through latest 3.2.x\n* 1.2.0 was an aborted version, don't use it, if you did, re-do your configuration according to current instructions and delete any local ./app/controllers/advanced_controller.rb file.\n* advanced search 1.1.x versions will work with Blacklights 3.0.x through 3.1.x\n* advanced search plugin latest 0.X.X version will work with Blacklight 2.9/Rails2.\n* Older tagged versions of Advanced Search may work with even older BL.\n\n## Installation\n\n### Blacklight 3.x/Rails 3\n\nAdd to your application's Gemfile:\n\n    gem \"blacklight_advanced_search\"\n\nthen run 'bundle install'.  Then run:\n\n    rails generate blacklight_advanced_search\n\n* The 'generate' command will install 'require' statements for the plugin's assets into your application's application.js/application.css asset pipeline files\n* 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.\n\nYou may want turn to enable AND/OR/NOT parsing even in ordinary search, this is not on by default.  See \"Expression parsing in ordinary search\" below.\n\n## Accessing\n\nThe advanced search form will be available in your app at /advanced, and in your app using\nrouting helper `advanced_search_path`.\n\n    advanced_search_path\n\nYou 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:\n\n    advanced_search_path( params )\n\nBy 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.\n\nHowever, 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.\n\n\n## Configuration\n\nIf 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. Most configuration takes place in your `./app/controllers/catalog_controller.rb` `configure_blacklight` block.\n\n\n### Expression parsing in ordinary search\n\nTurn this feature on by adding to your SearchBuilder definition:\n\n    self.default_processor_chain \u003c\u003c :add_advanced_parse_q_to_solr\n\nThis 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.\n\nIndividual blacklight 'search fields' can have advanced parsing turned off:\n\n    config.add_search_field(\"something\") do |field|\n      # ...\n      field.advanced_parse = false\n    end\n\n\nWhen 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.\n\nDue 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.\n\nIf there'a a parse error trying to parse as boolean expression, it'll give up and pass the query on through same as it would without ParseBasicQ.\n\n### Search fields\n\nYour main blacklight search fields are generally defined in CatalogController blacklight_config using `add_search_field`. They are all by default used in advanced search.\n\nIf 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 =\u003e false\"\n\n    config.add_search_field(\"isbn\") do |field|\n      field.include_in_advanced_search = false\n      field.solr_parameters = { :qf =\u003e \"isbn_t\" }\n    end\n\nIf you want search fields ONLY available in advanced search, you can suppress them from ordinary search:\n\n    config.add_search_field(\"publisher\") do |field|\n      field.include_in_simple_select = false\n      field.solr_parameters = { :qf =\u003e \"publisher_t\" }\n    end\n\nAll 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:\n\n    config.advanced_search = {\n      :qt =\u003e 'advanced'\n    }\n\nIf 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, just define them with `:include_in_advanced_search =\u003e true` and `:include_in_simple_search =\u003e false` as above.\n\nAdditionally, 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.\n\n    configure_blacklight do |config|\n      config.add_search_field('author') do |field|\n        field.solr_local_parameters = {\n          :qf=\u003e\"$qf_author\",\n          :pf=\u003e\"$pf_author\"\n        }\n      end\n    end\n\nWithin your solrconfig.xml you may then provide the appropriate custom configuration.\n\n    \u003crequestHandler name=\"advanced\" class=\"solr.SearchHandler\" \u003e\n      \u003clst name=\"defaults\"\u003e\n        \u003c!-- ... --\u003e\n        \u003cstr name=\"qf_author\"\u003e\n          author_1xx_unstem_search^200\n          author_7xx_unstem_search^50\n          author_8xx_unstem_search^10\n          author_1xx_search^20       vern_author_1xx_search^20\n          author_7xx_search^5        vern_author_7xx_search^5\n          author_8xx_search          vern_author_8xx_search\n        \u003c/str\u003e\n        \u003cstr name=\"pf_author\"\u003e\n          author_1xx_unstem_search^5000\n          author_7xx_unstem_search^3000\n          author_1xx_search^500        vern_author_1xx_search^500\n          author_7xx_search^300        vern_author_7xx_search^300\n          author_8xx_unstem_search^250\n          author_8xx_search^200        vern_author_8xx_search^200\n        \u003c/str\u003e\n      \u003c/lst\u003e\n    \u003c/requestHandler\u003e\n\n### Facets on advanced search form\n\nBy 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].\n\n    config.advanced_search = {\n      :form_solr_parameters =\u003e {\n        \"facet.field\" =\u003e [\"format\", \"language_facet\"],\n        \"facet.limit\" =\u003e -1, # return all facet values\n        \"facet.sort\" =\u003e \"index\" # sort by byte order of values\n      }\n    }\n\nMultiply selected advanced search form facets are combined with `or` (ie `any` or `union`).\n\nThe default advanced search form facet display is very much like Blacklight's\nsidebar facets (and uses some code straight from BL to render), but with checkboxes\nnext to each value.\n\n### Advanced Search Config Options\n\nComplete list of keys that can be supplied inside your configure_blacklight `advanced_search` block:\n\n* :qt\n  * Solr request handler to use for any search that includes advanced search criteria. Defaults to what the application has set as blacklight_config.default_solr_params[:qt]\n* :form_solr_parameters\n  * 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.\n* :query_parser\n  * advanced searches are translated to solr nested queries, where the inner queries are of a dismax-type.\n  By default, they are actually specifically 'dismax', but you can set :query_parser to 'edismax' instead.\n  This may make additional features available like * wildcards in advanced searches; but it may also\n  cause some user query elements to be interpreted as operators for edismax when they\n  were intended as literals. Somewhat experimental. See Github issues #11 and #14.\n\n## Customizing the advanced search form\n\nMost of the labels on the advanced search form are [provided via Rails i18n](./config/locales), and can\nbe customized in a local app i18n file.\n\nAdditionally, you can override the templates from this gem used to display the form.\nWe've tried to break it up into partials at the right granularity for over-riding\nin likely ways.  For one example, see the wiki page on [Adding a range limit to the advanced search form](https://github.com/projectblacklight/blacklight_advanced_search/wiki/Adding-a-range-limit-to-the-advanced-search-form).\n\n\n## Translation to Solr Query, technical details\n\nThe 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.\n\nSome technical details can be found in the nesting_parsing README: [https://github.com/projectblacklight/blacklight_advanced_search/tree/main/lib/parsing_nesting]\n\nYou may also find the rspecs for parsing a user-entered query and converting it to Solr illumnating:\n\n1. Converting user-entered query to Solr: [https://github.com/projectblacklight/blacklight_advanced_search/blob/main/spec/parsing_nesting/to_solr_spec.rb]\n2. Parsing user-entered query to internal syntax tree: [https://github.com/projectblacklight/blacklight_advanced_search/blob/main/spec/parsing_nesting/build_tree_spec.rb]\n\n## Running tests\n\n\n(Limited) test coverage is provided with rspec, run all tests (and start the jetty instance) by running:\n   rake ci\n\nfrom the blacklight_advanced_search directory. Note: you may need to `bundle install` first.\n\n\n## To Do\n\n* Alphabetical sorting of facet values returned by solr in count order (perhaps with limit).\n* Parse for fielded search too like \u003c\u003c title:\"some title\" \u003e\u003e.  'field:' that doesn't match an actual known field should be passed through same as now, while recognized fields should generate nested queries tied to those blacklight search types.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprojectblacklight%2Fblacklight_advanced_search","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprojectblacklight%2Fblacklight_advanced_search","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprojectblacklight%2Fblacklight_advanced_search/lists"}