blacklight 5.9.4 → 5.10.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/Gemfile +1 -1
- data/VERSION +1 -1
- data/app/assets/stylesheets/blacklight/_facets.scss +11 -10
- data/app/helpers/blacklight/blacklight_helper_behavior.rb +14 -14
- data/app/helpers/blacklight/configuration_helper_behavior.rb +16 -10
- data/app/helpers/blacklight/facets_helper_behavior.rb +15 -14
- data/app/helpers/blacklight/url_helper_behavior.rb +1 -1
- data/app/models/bookmark.rb +1 -4
- data/app/models/search.rb +3 -6
- data/app/views/catalog/_facet_layout.html.erb +2 -2
- data/app/views/catalog/_facet_limit.html.erb +5 -3
- data/app/views/catalog/_facet_pivot.html.erb +4 -4
- data/app/views/catalog/_home_text.html.erb +8 -48
- data/app/views/catalog/_index_default.html.erb +3 -3
- data/app/views/catalog/_show_default.html.erb +3 -3
- data/app/views/catalog/_sms_form.html.erb +1 -1
- data/app/views/catalog/facet.html.erb +1 -1
- data/blacklight.gemspec +1 -1
- data/config/jetty.yml +0 -3
- data/config/locales/blacklight.de.yml +2 -0
- data/config/locales/blacklight.en.yml +2 -0
- data/config/locales/blacklight.es.yml +2 -0
- data/config/locales/blacklight.fr.yml +2 -0
- data/config/locales/blacklight.pt-BR.yml +2 -0
- data/lib/blacklight.rb +70 -26
- data/lib/blacklight/abstract_repository.rb +29 -0
- data/lib/blacklight/base.rb +7 -7
- data/lib/blacklight/bookmarks.rb +5 -5
- data/lib/blacklight/catalog.rb +34 -19
- data/lib/blacklight/catalog/search_context.rb +1 -1
- data/lib/blacklight/configuration.rb +112 -46
- data/lib/blacklight/configuration/facet_field.rb +9 -7
- data/lib/blacklight/configuration/field.rb +27 -0
- data/lib/blacklight/configuration/fields.rb +25 -20
- data/lib/blacklight/configuration/search_field.rb +6 -8
- data/lib/blacklight/configuration/solr_field.rb +3 -18
- data/lib/blacklight/configuration/sort_field.rb +6 -7
- data/lib/blacklight/document.rb +156 -0
- data/lib/blacklight/document/dublin_core.rb +41 -0
- data/lib/blacklight/document/email.rb +16 -0
- data/lib/blacklight/document/export.rb +107 -0
- data/lib/blacklight/document/extensions.rb +56 -0
- data/lib/blacklight/document/schema_org.rb +7 -0
- data/lib/blacklight/document/semantic_fields.rb +51 -0
- data/lib/blacklight/document/sms.rb +14 -0
- data/lib/blacklight/document_presenter.rb +3 -3
- data/lib/blacklight/exceptions.rb +9 -2
- data/lib/blacklight/facet.rb +21 -16
- data/lib/blacklight/request_builders.rb +60 -284
- data/lib/blacklight/routes.rb +1 -1
- data/lib/blacklight/search_builder.rb +130 -0
- data/lib/blacklight/search_helper.rb +316 -0
- data/lib/blacklight/solr.rb +1 -0
- data/lib/blacklight/solr/document.rb +4 -187
- data/lib/blacklight/solr/document/dublin_core.rb +3 -37
- data/lib/blacklight/solr/document/email.rb +4 -13
- data/lib/blacklight/solr/document/export.rb +3 -103
- data/lib/blacklight/solr/document/extensions.rb +4 -52
- data/lib/blacklight/solr/document/more_like_this.rb +1 -1
- data/lib/blacklight/solr/document/schema_org.rb +4 -4
- data/lib/blacklight/solr/document/sms.rb +4 -11
- data/lib/blacklight/solr/facet_paginator.rb +2 -2
- data/lib/blacklight/solr/search_builder.rb +264 -0
- data/lib/blacklight/solr_helper.rb +6 -261
- data/lib/blacklight/solr_repository.rb +30 -24
- data/lib/blacklight/solr_response.rb +3 -3
- data/lib/blacklight/user.rb +1 -2
- data/lib/blacklight/utils.rb +0 -23
- data/lib/generators/blacklight/controller_generator.rb +38 -0
- data/lib/generators/blacklight/document_generator.rb +20 -0
- data/lib/generators/blacklight/install_generator.rb +38 -39
- data/lib/generators/blacklight/models_generator.rb +2 -62
- data/lib/generators/blacklight/templates/catalog_controller.rb +3 -4
- data/lib/generators/blacklight/templates/config/{solr.yml → blacklight.yml} +3 -0
- data/lib/generators/blacklight/templates/config/jetty.yml +0 -3
- data/lib/generators/blacklight/templates/solr_document.rb +6 -6
- data/lib/generators/blacklight/test_support_generator.rb +1 -6
- data/lib/generators/blacklight/user_generator.rb +59 -0
- data/lib/railties/blacklight.rake +16 -7
- data/spec/controllers/catalog_controller_spec.rb +9 -15
- data/spec/features/facets_spec.rb +8 -0
- data/spec/helpers/configuration_helper_spec.rb +6 -13
- data/spec/helpers/facets_helper_spec.rb +3 -2
- data/spec/lib/blacklight/configuration_spec.rb +11 -38
- data/spec/lib/blacklight/{solr/document → document}/dublin_core_spec.rb +4 -4
- data/spec/lib/blacklight/{solr/document → document}/email_spec.rb +2 -2
- data/spec/lib/blacklight/{solr/document → document}/sms_spec.rb +2 -2
- data/spec/lib/blacklight/search_builder_spec.rb +145 -0
- data/spec/lib/blacklight/search_helper_spec.rb +775 -0
- data/spec/lib/blacklight/solr/document/more_like_this_spec.rb +1 -1
- data/spec/lib/blacklight/solr/search_builder_spec.rb +561 -0
- data/spec/lib/blacklight/solr_helper_spec.rb +5 -1291
- data/spec/lib/blacklight/solr_repository_spec.rb +13 -13
- data/spec/models/record_mailer_spec.rb +2 -2
- data/spec/spec_helper.rb +1 -0
- data/spec/test_app_templates/lib/generators/test_app_generator.rb +1 -1
- data/spec/views/catalog/_constraints.html.erb_spec.rb +1 -1
- data/spec/views/catalog/_paginate_compact.html.erb_spec.rb +2 -2
- data/spec/views/catalog/index.atom.builder_spec.rb +1 -1
- data/tasks/blacklight.rake +1 -1
- data/template.demo.rb +1 -1
- metadata +33 -45
- data/doc/Adding-new-document-actions.md +0 -94
- data/doc/Atom-Responses.md +0 -90
- data/doc/Blacklight-Add-ons.md +0 -23
- data/doc/Blacklight-configuration.md +0 -411
- data/doc/Blacklight-on-Heroku.md +0 -100
- data/doc/Blacklight-out-of-the-box.md +0 -47
- data/doc/Bookmarks.md +0 -1
- data/doc/Code4Lib-2014.md +0 -94
- data/doc/Configuration---Facet-Fields.md +0 -130
- data/doc/Configuration---Results-View.md +0 -224
- data/doc/Configuration---Solr-fields.md +0 -106
- data/doc/Configuring-and-Customizing-Blacklight.md +0 -257
- data/doc/Configuring-rails-routes.md +0 -13
- data/doc/Contributing-to-Blacklight.md +0 -43
- data/doc/Examples.md +0 -120
- data/doc/Extending-or-Modifying-Blacklight-Search-Behavior.md +0 -141
- data/doc/Home.md +0 -100
- data/doc/How-to-release-a-version.md +0 -45
- data/doc/Indexing-your-data-into-solr.md +0 -36
- data/doc/Internationalization.md +0 -32
- data/doc/JSON-API.md +0 -83
- data/doc/Pagination.md +0 -52
- data/doc/Providing-your-own-view-templates.md +0 -69
- data/doc/Quickstart.md +0 -153
- data/doc/README_SOLR.md +0 -245
- data/doc/Saved-Searches.md +0 -5
- data/doc/Solr-Configuration.md +0 -154
- data/doc/Sunspot-for-indexing.md +0 -46
- data/doc/Support.md +0 -33
- data/doc/Theming.md +0 -62
- data/doc/Understanding-Rails-and-Blacklight.md +0 -75
- data/doc/User-Authentication.md +0 -60
- data/doc/_Sidebar.md +0 -9
- data/doc/testing.md +0 -58
@@ -1,141 +0,0 @@
|
|
1
|
-
# Extending or Modifying Blacklight Search Behavior
|
2
|
-
|
3
|
-
Solr parameters used by for a given request can come from several different places.
|
4
|
-
|
5
|
-
* Solr request handler: `solrconfig.xml` in your solr config
|
6
|
-
* Application logic: logic in the BL rails app itself
|
7
|
-
|
8
|
-
## Solr request handler
|
9
|
-
|
10
|
-
The Solr [Request Handlers](http://wiki.apache.org/solr/SolrRequestHandler) may be configured in the [solrconfig.xml](http://wiki.apache.org/solr/SolrConfigXml) and are baked into the request handler itself. Depending on how you have blacklight configured, your app may be using the same Solr request handler for all searches, or may be using different request handlers for different "search fields".
|
11
|
-
|
12
|
-
The request handler is often set up with default parameters:
|
13
|
-
|
14
|
-
```xml
|
15
|
-
<requestHandler name="standard" class="solr.SearchHandler" >
|
16
|
-
<lst name="defaults">
|
17
|
-
<str name="echoParams">explicit</str>
|
18
|
-
<str name="rows">10</str>
|
19
|
-
<str name="fl">*</str>
|
20
|
-
<str name="facet">true</str>
|
21
|
-
<str name="facet.mincount">1</str>
|
22
|
-
<str name="facet.limit">30</str>
|
23
|
-
<str name="facet.field">access_facet</str>
|
24
|
-
<str name="facet.field">author_person_facet</str>
|
25
|
-
<str name="facet.field">author_other_facet</str>
|
26
|
-
<str name="facet.field">building_facet</str>
|
27
|
-
<str name="facet.field">callnum_1_facet</str>
|
28
|
-
<str name="facet.field">era_facet</str>
|
29
|
-
<str name="facet.field">format</str>
|
30
|
-
<str name="facet.field">geographic_facet</str>
|
31
|
-
<str name="facet.field">language</str>
|
32
|
-
<str name="facet.field">pub_date_group_facet</str>
|
33
|
-
<str name="facet.field">topic_facet</str>
|
34
|
-
</lst>
|
35
|
-
</requestHandler>
|
36
|
-
```
|
37
|
-
## Configuration
|
38
|
-
|
39
|
-
The default application logic (explained below) looks in configuration for things like the name of a the solr request handler to use, and default request parameters to send on every solr search request (or with every request from a certain blacklight search type/field). An example getting started configuration is generally installed into your app when you install Blacklight at [`./app/controllers/catalog_controller.rb`](https://github.com/projectblacklight/blacklight/blob/master/lib/generators/blacklight/templates/catalog_controller.rb).
|
40
|
-
|
41
|
-
## Application logic
|
42
|
-
|
43
|
-
The logic Blacklight uses to determine how to map user-supplied parameters into Solr request parameters for a given application request is in the [#solr_search_params method in the SolrHelper module](https://github.com/projectblacklight/blacklight/blob/master/lib/blacklight/solr_helper.rb#L76). Note that [CatalogController](https://github.com/projectblacklight/blacklight/blob/master/app/controllers/catalog_controller.rb) extends [SolrHelper](https://github.com/projectblacklight/blacklight/blob/master/lib/blacklight/solr_helper.rb), so the `SolrHelper` methods become available in the `CatalogController` (and other controllers, if they extend `SolrHelper` too).
|
44
|
-
|
45
|
-
Behind the scenes, #solr_search_params uses the `class_inheritable_accessor` method [`solr_search_params_logic`](https://github.com/projectblacklight/blacklight/blob/master/lib/blacklight/solr_helper.rb#L30). solr_search_params_logic is essentially a class variable that is mixed into the CatalogController and provides an ordered list of methods to call that may inspect the supplied user parameters and add, remove, or modify the Solr request parameters that will be sent to an [RSolr](https://github.com/mwmitchell/rsolr/) object, which in turn will convert the hash into query parameters for a Solr request. One confusing thing is that RSolr and [RSolr-ext](https://github.com/mwmitchell/rsolr-ext) provide their own mappings from certain custom terms to Solr-recognized request parameters. For instance, a `:per_page` key in that hash will get mapped to the Solr `&rows` parameter -- but a `:rows` key will also. Blacklight developers have found that using these special RSolr "aliases" leads to confusion, as well as confusing bugs (if both `:per_page` and `:rows` are set in the hash, what happens can be hard to predict). So we try to avoid using the special RSolr aliases, and just use ordinary Solr parameters in our hashes. But you may encounter older code that uses the RSolr aliases.
|
46
|
-
|
47
|
-
There can be similar confusing behavior or bugs if one piece of code adds a key to a `Hash` using a `Symbol`, but another piece of code looks for and/or adds that same key to the `Hash` using a `String` instead. RSolr happens to accepts either one, but if both are present RSolr behavior can be unexpected. And even before it gets to RSolr, you may have code that thinks it replaced a key but did not becuase it was using the wrong form. Blacklight developers have agreed to try and always use `Symbol` based keys in hashes meant for Solr parameters, to try and avoid these problems. Longer term, we could probably make some code changes to make this kind of error less likely.
|
48
|
-
|
49
|
-
The default `#solr_search_params_logic` is meant to handle very common cases and patterns based on simple configuration options from the controller and the user-supplied URL parameters.
|
50
|
-
|
51
|
-
* [`blacklight_config.default_solr_params`](https://github.com/projectblacklight/blacklight/blob/master/lib/generators/blacklight/templates/catalog_controller.rb#L9)
|
52
|
-
* Default params sent to solr with every search, including the default :qt param, which determines which Solr request handler will be targetted. Some people like to use solrconfig.xml request handler defaults exclusively, and include only a :qt here; others find it more convenient to specify some defaults at the application level here.
|
53
|
-
* [`blacklight_config.search_fields`](https://github.com/projectblacklight/blacklight/blob/master/lib/generators/blacklight/templates/catalog_controller.rb#L81)
|
54
|
-
* Each search field will be presented in a select menu in the BL user interface search box. These 'search fields' don't neccesarily correspond 1-to-1 with Solr fields. What they instead correspond to is Solr parameter over-rides that will be used for this BL UI search field. Those over-rides are present here.
|
55
|
-
* You could simply chose a different `:qt` Solr request handler for each search field, which has it's own default parameters in the sorlconfig.xml. This is what we started out doing with Solr, but found it led to much duplication of information in solrconfig.xml.
|
56
|
-
* You can continue using the same Solr request handler, but simply specify different parameters which will be included in the http query string sent to Solr here, with the `:solr_parameters` key. This works fine, but some people don't like how it makes your Solr requests much longer/more complex in the Solr logs; and/or they prefer to control this Solr side instead of Application side.
|
57
|
-
* For the best of both worlds, although it's a bit confusing at first, you can use the `:solr_local_parameters` key to have parameters supplied to Solr using the Solr [LocalParams](http://wiki.apache.org/solr/LocalParams) syntax, which means you can use "parameter dereferencing" with dollar-sign-prefixed references to variables defined in solrconfig.xml request handler. This is what the current example BL setup does.
|
58
|
-
|
59
|
-
So the default implementation of `#solr_search_params` takes these configured parameters, combines them with certain query parameters from the current users HTTP request to the BL app, and prepares a Hash of parameters that will be sent to solr. For common use patterns, this is all you need.
|
60
|
-
|
61
|
-
But sometimes you want to add some custom logic to `#solr_search_params` to come up with the solr params Hash in different ways. Typically to support a new UI feature of some kind, either in your local app or in a Blacklight add-on plugin you are developing.
|
62
|
-
|
63
|
-
|
64
|
-
# Extending Blacklight::SolrHelper#solr_search_params
|
65
|
-
|
66
|
-
To add new search behaviors (e.g. authorization controls, pre-parsing query strings, etc), the easiest route is to add additional steps to the `#solr_search_params_logic`, either at the beginning of the list (to set default parameters) or at the end of the list (to force particular parameters). Because `#solr_search_params_logic` is just an ordinary array, you may perform any normal array operation (e.g. push/pop/delete/insert) to customize the parameter generation to meet your needs.
|
67
|
-
|
68
|
-
`#solr_search_params_logic` steps take two inputs, the hash of `solr_parameters` and the hash of `user_parameters` (often provided by the URL parameters), and modifies the `solr_parameters` directly, as needed.
|
69
|
-
|
70
|
-
You can add custom solr_search_params_logic steps within your controller (or in many other places, including initializers, mixins, etc) by adding a Symbol with the name of a method (provided by the controller) you wish to use, e.g.:
|
71
|
-
|
72
|
-
*./config/initializers/blacklight_config.rb*
|
73
|
-
|
74
|
-
```ruby
|
75
|
-
class CatalogController
|
76
|
-
self.solr_search_params_logic += :show_only_public_records
|
77
|
-
end
|
78
|
-
```
|
79
|
-
The controller must provide the method added to `solr_search_params_logic`, in this case `show_only_public_records`. It is often convenient to do this in a separate `Module` and include it into the controller:
|
80
|
-
|
81
|
-
*./app/controllers/catalog_controller.rb*
|
82
|
-
|
83
|
-
```ruby
|
84
|
-
require 'blacklight/catalog'
|
85
|
-
class CatalogController < ApplicationController
|
86
|
-
include Blacklight::Catalog
|
87
|
-
include MyApplication::SolrHelper::Authorization
|
88
|
-
|
89
|
-
# Instead of defining this within an initializer, you may instead wish to do it on the controller directly:
|
90
|
-
# self.solr_search_params_logic += [:show_only_public_records]
|
91
|
-
|
92
|
-
# You could also define the actual method here, but this is not recommended.
|
93
|
-
# def show_only_public_records solr_parameters, user_parameters
|
94
|
-
# [...]
|
95
|
-
# end
|
96
|
-
end
|
97
|
-
```
|
98
|
-
|
99
|
-
The included module then defines the logic method:
|
100
|
-
|
101
|
-
*./lib/my_application/solr_helper/authorization.rb*
|
102
|
-
|
103
|
-
```ruby
|
104
|
-
module MyApplication::SolrHelper::Authorization
|
105
|
-
# You could also add the logic here
|
106
|
-
# def self.included base
|
107
|
-
# base.solr_search_params_logic += [:show_only_public_records]
|
108
|
-
# end
|
109
|
-
|
110
|
-
# solr_search_params_logic methods take two arguments
|
111
|
-
# @param [Hash] solr_parameters a hash of parameters to be sent to Solr (via RSolr)
|
112
|
-
# @param [Hash] user_parameters a hash of user-supplied parameters (often via `params`)
|
113
|
-
def show_only_public_records solr_parameters, user_parameters
|
114
|
-
# add a new solr facet query ('fq') parameter that limits results to those with a 'public_b' field of 1
|
115
|
-
solr_parameters[:fq] ||= []
|
116
|
-
solr_parameters[:fq] << 'public_b:1'
|
117
|
-
end
|
118
|
-
end
|
119
|
-
```
|
120
|
-
|
121
|
-
## Other examples
|
122
|
-
|
123
|
-
In addition to providing this behavior locally, some Blacklight plugins also extend the `#solr_search_params`:
|
124
|
-
|
125
|
-
* [Blacklight Range Limit](https://github.com/projectblacklight/blacklight_range_limit/blob/master/lib/blacklight_range_limit/controller_override.rb)
|
126
|
-
|
127
|
-
* A walk through on adding a checkbox limit at: http://bibwild.wordpress.com/2011/06/13/customing-blacklight-a-limit-checkbox/
|
128
|
-
|
129
|
-
* A much more complicated walk-through on adding an 'unstemmed search' checkbox limit: http://bibwild.wordpress.com/2011/06/20/customizing-blacklight-disable-automatic-stemming/
|
130
|
-
|
131
|
-
## Suppressing search results
|
132
|
-
|
133
|
-
You can configure your `solrconfig.xml` to not show results based on fields in your solr document. For example, if you have a solr boolean field such as `show_b`, you can suppress any records that have this field present. To do so, add:
|
134
|
-
```
|
135
|
-
<lst name="appends"><str name="fq">-show_b:["" TO *]</str></lst>
|
136
|
-
```
|
137
|
-
to the request handler in your `solrconfig.xml` file. If you would like this to be for standard solr searches, add the above line to this request handler:
|
138
|
-
```
|
139
|
-
<requestHandler name="search" class="solr.SearchHandler" default="true">
|
140
|
-
```
|
141
|
-
By doing so, solr queries that use the "document" request handler will still give you any records with the show_b field, but solr queries with the "search" handler will not.
|
data/doc/Home.md
DELETED
@@ -1,100 +0,0 @@
|
|
1
|
-
> NOTE: This wiki provides developer documentation for the latest Blacklight release. For documentation of older releases, see the end of this page.
|
2
|
-
|
3
|
-
Blacklight is an open source, Ruby on Rails Engine that provides a basic discovery interface for searching an [Apache Solr](http://lucene.apache.org/solr) index, and provides search box, facet constraints, stable document urls, etc., all of which is customizable via Rails (templating) mechanisms. Blacklight accommodates heterogeneous data, allowing different information displays for different types of objects.
|
4
|
-
|
5
|
-
Some other features include:
|
6
|
-
|
7
|
-
* Stable URLs for search and record pages allow users to bookmark, share, and save search queries for later access
|
8
|
-
* Every Blacklight search provides RSS and Atom Responses of search results
|
9
|
-
* For certain types of solr documents, an OpenURL/Z39.88 COinS object is embedded in each document, which allows plugins like Zotero to easily extract data from the page.
|
10
|
-
* Blacklight supports OpenSearch, a collection of simple formats for the sharing of search results.
|
11
|
-
* Faceted searching
|
12
|
-
* Search queries can be targeted at specific sets of fields
|
13
|
-
* Results sorting
|
14
|
-
* Tools for exporting records to Refworks or Endnote, sending records via Email or SMS, or as a formatted citation.
|
15
|
-
|
16
|
-
## About this guide
|
17
|
-
|
18
|
-
This wiki provides high-level documentation of Blacklight and supplements the low-level [RubyDocs](http://rubydoc.info/gems/blacklight). It is structured to address a broad spectrum of needs, ranging from new developers getting started to well-experienced developers extending their application or troubleshooting. It should be of use at any point in the application life cycle.
|
19
|
-
|
20
|
-
This wiki assumes you have prior experience with Ruby and Ruby on Rails. If you have no prior experience with either, you will find a very steep learning curve diving straight into Blacklight. There are some good free resources on the internet for learning Ruby, including:
|
21
|
-
|
22
|
-
- [Mr. Neighborly's Humble Little Ruby Book](http://www.humblelittlerubybook.com/)
|
23
|
-
- [Programming Ruby](http://ruby-doc.com/docs/ProgrammingRuby/)
|
24
|
-
- [Why's (Poignant) Guide to Ruby](http://mislav.uniqpath.com/poignant-guide/)
|
25
|
-
|
26
|
-
And resources for learning Rails, including:
|
27
|
-
|
28
|
-
- [Rails tutorial](http://ruby.railstutorial.org/)
|
29
|
-
- [Learn Rails](https://learn.thoughtbot.com/rails)
|
30
|
-
- [Railsbridge](http://docs.railsbridge.org/docs/)
|
31
|
-
|
32
|
-
In order to fully understand this guide, you should also familiarize yourself with Apache Solr, ways to index data into Solr, how to configure request handlers, and the Solr schema format. Those topics are covered in the official [Apache Solr Tutorial](http://lucene.apache.org/solr/tutorial.html).
|
33
|
-
|
34
|
-
## Blacklight features
|
35
|
-
* [[Basic features|Blacklight out-of-the-box]]
|
36
|
-
* [[Internationalization]]: Translating (or simply customizing) the Blacklight copy
|
37
|
-
* APIs: [[Atom Responses]], [[JSON API]]
|
38
|
-
* [[Directory of Blacklight Plugins/Addons|Blacklight-Add-ons]]
|
39
|
-
|
40
|
-
## Blacklight Configuration
|
41
|
-
|
42
|
-
Blacklight tries to address the "80% use case" out of the box and through some simple configuration can be adapted to work with your data. The available Blacklight configuration, and their default values, is shown in
|
43
|
-
[`blacklight/configuration.rb`](https://github.com/projectblacklight/blacklight/tree/master/lib/blacklight/configuration.rb).
|
44
|
-
|
45
|
-
The Blacklight configuration is an `OpenStruct`; in addition to the Blacklight-defined configuration discussed in the sections below, you may also add application-specific configuration (e.g. for controlling behavior in overridden partials) or plugin-specific configuration.
|
46
|
-
|
47
|
-
* [[Solr Configuration]]
|
48
|
-
* [[Discovery|Configuration - Solr fields]]
|
49
|
-
* [[Results view|Configuration - Results View]]
|
50
|
-
* [[Facets|Configuration - Facet Fields]]
|
51
|
-
|
52
|
-
## Blacklight Customization
|
53
|
-
|
54
|
-
There are many ways to override specific behaviors and views in Blacklight. Because Blacklight is distributed as a Rails engine-based gem, all customization of Blacklight behavior should be done within your application by overriding Blacklight-provided behaviors with your own.
|
55
|
-
|
56
|
-
* [[Understanding Rails and Blacklight]] How the Blacklight engine integrates with your application
|
57
|
-
* [[Extending or Modifying Blacklight Search Behavior]] How to change the way the Blacklight discovery feature works.
|
58
|
-
* [[Adding new document actions]] How to extend the document actions with application-specific behavior
|
59
|
-
|
60
|
-
### Customizing the UI
|
61
|
-
|
62
|
-
* [[Theming]]: Overriding the Blacklight CSS
|
63
|
-
* [[Providing your own view templates]]: Overriding the out-of-the-box Blacklight templates the Rails way.
|
64
|
-
* [[Pagination]]: Advice on how to customize pagination with Kaminari
|
65
|
-
|
66
|
-
### Other Customizations
|
67
|
-
* [[User Authentication]]: Connecting Blacklight with an existing Authentication system
|
68
|
-
* [[Configuring Rails Routes]]
|
69
|
-
* [[Indexing your data into Solr]]
|
70
|
-
* [[Additional Blacklight-specific Solr documentation|README_SOLR]]
|
71
|
-
|
72
|
-
## Support
|
73
|
-
Don't be scared to ask a question on the [[Blacklight mailing list|http://groups.google.com/group/blacklight-development]]. We appreciate you checking the documentation first and asking an educated question, but don't beat your head against the wall -- sometimes the existing documentation may be out of date and inaccurate.
|
74
|
-
|
75
|
-
In order to reduce spam, the first time you post your email will be held in a moderation queue, but as soon as your first message is approved your posts won’t be held for moderation any longer.
|
76
|
-
|
77
|
-
Some Blacklight developers aso hang out on our IRC channel, usually during North American office hours. On `chat.freenode.net`, channel `#blacklight`. Stop in and say hi, we're happy to help with questions when we have time. [[http://freenode.net/faq.shtml]].
|
78
|
-
|
79
|
-
* [[Bug Tracker|https://github.com/projectblacklight/blacklight/issues/]]
|
80
|
-
* [[Mailing List|http://groups.google.com/group/blacklight-development]]
|
81
|
-
* [![Build Status](https://travis-ci.org/projectblacklight/blacklight.png?branch=master)](https://travis-ci.org/projectblacklight/blacklight)
|
82
|
-
|
83
|
-
## Contributing to Blacklight
|
84
|
-
|
85
|
-
* [[Contributing to Blacklight]]
|
86
|
-
* [[How to release a version]]
|
87
|
-
* [[Testing]]
|
88
|
-
|
89
|
-
### Older Documentation
|
90
|
-
This wiki provides developer documentation for the ```master``` branch of Blacklight, which may include documentation of features not present in every Blacklight version. For documentation of specific Blacklight releases, see also:
|
91
|
-
|
92
|
-
* [[Home]]
|
93
|
-
* [[Blacklight 4.7|https://github.com/projectblacklight/blacklight/tree/release-4.7/doc]]
|
94
|
-
* [[Blacklight 3.x|https://github.com/projectblacklight/blacklight/tree/release-3.8/doc]]
|
95
|
-
* [[Blacklight 3.0 or 3.1|https://github.com/projectblacklight/blacklight/tree/release-3.1/doc]]
|
96
|
-
* [[Blacklight 2.x|https://github.com/projectblacklight/blacklight/tree/v2.9-frozen/doc]] for all Blacklight 2.x releases; version-specific documentation is also available:
|
97
|
-
* [[Blacklight 2.7|https://github.com/projectblacklight/blacklight/tree/v2.7.0/doc]]
|
98
|
-
* [[Blacklight 2.6|https://github.com/projectblacklight/blacklight/tree/v2.6.0/doc]]
|
99
|
-
* [[Blacklight 2.5|https://github.com/projectblacklight/blacklight/tree/v2.5.0/doc]]
|
100
|
-
* [[Blacklight 2.4|https://github.com/projectblacklight/blacklight/tree/v2.4.2/doc]]
|
@@ -1,45 +0,0 @@
|
|
1
|
-
Before releasing, ensure that you're on the master branch. Run all tests and ensure that they pass. Also check the [[continuous integration server|https://travis-ci.org/projectblacklight/blacklight]] to make sure tests are passing.
|
2
|
-
```bash
|
3
|
-
$ bundle exec rake
|
4
|
-
```
|
5
|
-
|
6
|
-
1. Update the version number in ./VERSION
|
7
|
-
```
|
8
|
-
{major}.{minor}.{patch}
|
9
|
-
```
|
10
|
-
|
11
|
-
1. Fix GitHub issue tracker to know about the release
|
12
|
-
* Create a milestone in GitHub for the NEXT version.
|
13
|
-
* Move any open tickets for released version to the next version.
|
14
|
-
* Mark the milestone as closed.
|
15
|
-
|
16
|
-
1. Write Github [release notes](https://github.com/projectblacklight/blacklight/tags) for the tag, using this template:
|
17
|
-
|
18
|
-
```code
|
19
|
-
[Commit History](https://github.com/projectblacklight/blacklight/compare/v5.x.0...v5.x.0) | [Milestone](https://github.com/projectblacklight/blacklight/issues?q=milestone:{milestone here})
|
20
|
-
|
21
|
-
(anything important about this release, themes, etc)
|
22
|
-
|
23
|
-
### New Features and improvements
|
24
|
-
|
25
|
-
(#ticketnumber and a human-readable description of the ticket, usually the ticket title. If the ticket title doesn't make sense, either edit the ticket directly, or provide an alternative title here)
|
26
|
-
|
27
|
-
## Bug Fixes
|
28
|
-
|
29
|
-
### Upgrade Notes
|
30
|
-
|
31
|
-
(anything special that needs to be called out)
|
32
|
-
```
|
33
|
-
|
34
|
-
1. Prepare announcement
|
35
|
-
* Include URL to GitHub closed issues for version
|
36
|
-
* Include URL to github commits between tags. github can show all commits between two versions with a URL of this form: [[http://github.com/projectblacklight/blacklight/compare/v2.5.0...v2.6.0]] Replace with previous version and current release version tags.
|
37
|
-
* Include URL to the Github release notes
|
38
|
-
|
39
|
-
1. Release the gem
|
40
|
-
```bash
|
41
|
-
$ rake release
|
42
|
-
```
|
43
|
-
|
44
|
-
1. Announce
|
45
|
-
* Write emails announcing the release to Blacklight Development
|
@@ -1,36 +0,0 @@
|
|
1
|
-
Blacklight uses Solr as its data index. Blacklight is agnostic as to how that Solr index gets populated. Initial Blacklight development was geared towards work in university libraries, and deals with library data in the MARC format. The Blacklight out-of-the-box demo and test suite is geared towards that use case, but Blacklight itself is not limited to only serving MARC-based data.
|
2
|
-
|
3
|
-
## Common Patterns
|
4
|
-
|
5
|
-
* [[Sunspot for Indexing]]
|
6
|
-
|
7
|
-
* If you're not dealing with MARC records, you might do something like the following:
|
8
|
-
|
9
|
-
```
|
10
|
-
class MyModel < ActiveRecord::Base
|
11
|
-
after_save :index_record
|
12
|
-
before_destroy :remove_from_index
|
13
|
-
|
14
|
-
attr_accessible :field_i_want_to_index
|
15
|
-
|
16
|
-
def to_solr
|
17
|
-
# *_texts here is a dynamic field type specified in solrconfig.xml
|
18
|
-
{'id' => id,
|
19
|
-
'field_i_want_to_index_texts' => field_i_want_to_index}
|
20
|
-
end
|
21
|
-
|
22
|
-
def index_record
|
23
|
-
SolrService.add(self.to_solr)
|
24
|
-
SolrService.commit
|
25
|
-
end
|
26
|
-
|
27
|
-
def remove_from_index
|
28
|
-
SolrService.delete_by_id(self.id)
|
29
|
-
SolrService.commit
|
30
|
-
end
|
31
|
-
end
|
32
|
-
```
|
33
|
-
|
34
|
-
## What’s the relationship between Blacklight and SolrMarc?
|
35
|
-
|
36
|
-
However, one excellent way to index lots of MARC records into Solr quickly is to use SolrMarc. Some of the same people are active in both projects, e.g, Bob Haschart from UVA and Naomi Dushay from Stanford University. SolrMarc is not a Blacklight-specific project, it is also used by VuFind and other projects, and is a separate project that exists in its own right.
|
data/doc/Internationalization.md
DELETED
@@ -1,32 +0,0 @@
|
|
1
|
-
Blacklight uses the [Rails i18n framework](http://guides.rubyonrails.org/i18n.html) to provide multilingual version of most text in the Blacklight default templates. Blacklight ships with a set of English and French translations in [config/locales](https://github.com/projectblacklight/blacklight/blob/master/config/locales/).
|
2
|
-
|
3
|
-
In addition to multilingual support, developments can also e.g. customize the English strings in Blacklight-based applications, which provides a way to change text without overriding templates and partials.
|
4
|
-
|
5
|
-
## A quick i18n example
|
6
|
-
A locale entry that looks like this:
|
7
|
-
|
8
|
-
```yaml
|
9
|
-
en:
|
10
|
-
blacklight:
|
11
|
-
application_name: 'Blacklight'
|
12
|
-
```
|
13
|
-
|
14
|
-
Is referenced in the Blacklight code as:
|
15
|
-
|
16
|
-
```ruby
|
17
|
-
I18n.t 'blacklight.application_name'
|
18
|
-
# OR
|
19
|
-
t('blacklight.application_name')
|
20
|
-
```
|
21
|
-
|
22
|
-
You could override this in your application's ```config/locales/en.yml```:
|
23
|
-
|
24
|
-
```yaml
|
25
|
-
en:
|
26
|
-
blacklight:
|
27
|
-
application_name: 'My Blacklight Application'
|
28
|
-
```
|
29
|
-
|
30
|
-
And then everywhere Blacklight views show the application name, it will use your label ("My Blacklight Application") instead of ours ("Blacklight").
|
31
|
-
|
32
|
-
There are other i18n tricks (that we use) covered in the [Rails i18n Rails guide|http://guides.rubyonrails.org/i18n.html], including pluralization, interpolation, etc.
|
data/doc/JSON-API.md
DELETED
@@ -1,83 +0,0 @@
|
|
1
|
-
Blacklight's search, show and facets have JSON responses. The default serializations are very basic, but should be enough to drive simple AJAX widgets.
|
2
|
-
|
3
|
-
### Search results
|
4
|
-
`/catalog.json?search_field=all_fields&q=auckland`
|
5
|
-
|
6
|
-
```json
|
7
|
-
{
|
8
|
-
"response":{
|
9
|
-
"docs":[
|
10
|
-
{ "title_display":"Maine",
|
11
|
-
"id":"2009002583",
|
12
|
-
"author_display":"Dornfeld, Margaret",
|
13
|
-
"format":"Book",
|
14
|
-
"isbn_t":["9780761447269"],
|
15
|
-
"published_display":["New York"],
|
16
|
-
"lc_callnum_display":["F19.3 .D67 2011"],
|
17
|
-
"subject_geo_facet":["Maine"],
|
18
|
-
"pub_date":["2011"],
|
19
|
-
"language_facet":["English"],
|
20
|
-
"material_type_display":["p. cm"],
|
21
|
-
"score":9.667667},
|
22
|
-
{"title_display":"Ghostly lighthouses from Maine to Florida","id":"2005005219","author_display":"Monks, Sheryl, 1967-","format":"Book"},
|
23
|
-
...
|
24
|
-
],
|
25
|
-
"pages": {
|
26
|
-
"current_page":1,
|
27
|
-
"next_page":2,
|
28
|
-
"prev_page":null,
|
29
|
-
"total_pages":7,
|
30
|
-
"limit_value":10,
|
31
|
-
"offset_value":0,
|
32
|
-
"total_count":61,
|
33
|
-
"first_page?":true,
|
34
|
-
"last_page?":false
|
35
|
-
}
|
36
|
-
}
|
37
|
-
}
|
38
|
-
```
|
39
|
-
|
40
|
-
### Facet list
|
41
|
-
`/catalog/facet/subject_topic_facet.json`
|
42
|
-
|
43
|
-
```json
|
44
|
-
{
|
45
|
-
"response": {
|
46
|
-
"facets": {
|
47
|
-
"offset":0,
|
48
|
-
"sort":"count",
|
49
|
-
"items": [
|
50
|
-
{"value":"Book","hits":9737},
|
51
|
-
{"value":"Unknown","hits":88}
|
52
|
-
],
|
53
|
-
"has_next":false,
|
54
|
-
"has_previous":false,
|
55
|
-
"limit":20
|
56
|
-
}
|
57
|
-
}
|
58
|
-
}
|
59
|
-
```
|
60
|
-
|
61
|
-
### Single record
|
62
|
-
`/catalog/2009002600.json`
|
63
|
-
|
64
|
-
```json
|
65
|
-
{
|
66
|
-
"response":{
|
67
|
-
"document":{
|
68
|
-
"title_display":"Nebraska",
|
69
|
-
"id":"2009002600",
|
70
|
-
"author_display":"Bjorklund, Ruth",
|
71
|
-
....
|
72
|
-
}
|
73
|
-
}
|
74
|
-
}
|
75
|
-
```
|
76
|
-
|
77
|
-
The JSON serialization can be overridden in a local application by providing alternative implementations of:
|
78
|
-
* `render_search_results_as_json`
|
79
|
-
* `render_facet_list_as_json`
|
80
|
-
|
81
|
-
in your CatalogController.
|
82
|
-
|
83
|
-
See: https://github.com/projectblacklight/blacklight/blob/master/lib/blacklight/catalog.rb#L175-L191
|
data/doc/Pagination.md
DELETED
@@ -1,52 +0,0 @@
|
|
1
|
-
Blacklight uses [kaminari](https://github.com/amatsuda/kaminari) for providing pagination of Solr responses.
|
2
|
-
|
3
|
-
One motivation for this is so a pagination view theme can be provided that you can use for your custom code with ordinary ActiveRecord or anything else kaminari can handle, to have consistency between the rest of your app's pagination and Blacklight's Solr response pagination.
|
4
|
-
|
5
|
-
## How it works
|
6
|
-
|
7
|
-
The Blacklight response objects are Kaminari-ready #paginate, so you could call:
|
8
|
-
|
9
|
-
paginate(@response ) # where @response is an RSolr::Response
|
10
|
-
|
11
|
-
Or,
|
12
|
-
paginate @response, :theme => 'blacklight'
|
13
|
-
|
14
|
-
![Blacklight theme](https://f.cloud.github.com/assets/111218/2059081/97fe4082-8b95-11e3-9fd2-ae824bcf7b7e.png)
|
15
|
-
|
16
|
-
The `theme => 'blacklight'` part will be passed through kaminari, and tell kaminari to use the theme that the Blacklight plugin supplies at [app/views/kaminari/blacklight](https://github.com/projectblacklight/blacklight/tree/master/app/views/kaminari/blacklight)
|
17
|
-
|
18
|
-
Any other arguments of ordinary kaminari paginate can also be passed in there.
|
19
|
-
|
20
|
-
Additionally, we sometimes want to output a "X through Y of N" message with some basic pagination controls, which kaminari doesn't have a (good) way to do by default. Blacklight provides a simple partial to provide this behavior:
|
21
|
-
|
22
|
-
```ruby
|
23
|
-
render partial: 'catalog/paginate_compact', object: @response
|
24
|
-
```
|
25
|
-
|
26
|
-
Or, using all kaminari-native methods:
|
27
|
-
|
28
|
-
```erb
|
29
|
-
<%= paginate paginate_compact, :page_entries_info => page_entries_info(paginate_compact), :theme => :blacklight_compact %>
|
30
|
-
```
|
31
|
-
|
32
|
-
![Compact](https://f.cloud.github.com/assets/111218/2059080/97fc3ee0-8b95-11e3-8c66-ab31dcd7eedb.png)
|
33
|
-
|
34
|
-
## Changing the kaminari theme
|
35
|
-
|
36
|
-
If you want to change how pagination links are rendered, the easiest/cleanest thing to do is to over-ride the 'blacklight' theme that the Blacklight plugin defines. Copy the view templates in Blacklight source at app/views/kaminari/blacklight to your own local app/views/kaminari/blacklight. You actually only need to copy files you'll want to modify, templates not overridden with a local copy will still be found by kaminari from the Blacklight gem. You can use any techniques available for creating a kaminari theme when editing these files, including over-riding more kaminari view templates if available. See the kaminari documentation.
|
37
|
-
|
38
|
-
There are other ways you could change how Blacklight pagination renders, but by doing it this way, any code (in core Blacklight or additional plugins you install) that tries to render pagination using kaminari with 'blacklight' theme will get your locally defined theme.
|
39
|
-
|
40
|
-
## Changing the default kaminari pagination options
|
41
|
-
|
42
|
-
Sometimes you you just want to tweak a few things with pagination and it doesn't require crawling into the RSolr response or creating a kaminari theme. Here's how you do that.
|
43
|
-
|
44
|
-
First, generate the kaminari config initializer:
|
45
|
-
|
46
|
-
rails g kaminari:config
|
47
|
-
|
48
|
-
You will get a file in config/initializers/kaminari_config.rb that is mostly commented out. The config options are mostly self-explanatory, but let's say that you don't like that Blacklight gives you 4 pages of links on either side of the current page. Uncomment:
|
49
|
-
|
50
|
-
# config.window = 4
|
51
|
-
|
52
|
-
and change 4 to whatever number is preferable. More information on the kaminari general configuration options is available here: https://github.com/amatsuda/kaminari#general-configuration-options
|