blacklight 4.6.3 → 4.7.0.pre1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (70) hide show
  1. checksums.yaml +4 -4
  2. data/VERSION +1 -1
  3. data/app/controllers/bookmarks_controller.rb +4 -0
  4. data/app/helpers/blacklight/blacklight_helper_behavior.rb +76 -21
  5. data/app/helpers/blacklight/hash_as_hidden_fields_helper_behavior.rb +8 -1
  6. data/app/views/catalog/_citation.html.erb +1 -1
  7. data/app/views/catalog/_did_you_mean.html.erb +1 -1
  8. data/app/views/catalog/_search_form.html.erb +1 -1
  9. data/blacklight.gemspec +1 -1
  10. data/config/locales/blacklight.en.yml +3 -0
  11. data/config/locales/blacklight.fr.yml +3 -0
  12. data/doc/Atom-Responses.md +90 -0
  13. data/doc/Blacklight-3.0-Release-Notes-And-Upgrade-Guide.md +107 -0
  14. data/doc/Blacklight-3.2-Release-Notes-and-Upgrade-Guide.md +191 -0
  15. data/doc/Blacklight-3.3-release-notes-and-upgrade-guide.md +37 -0
  16. data/doc/Blacklight-3.4-release-notes-and-upgrade-guide.md +27 -0
  17. data/doc/Blacklight-3.5-release-notes-and-upgrade-guide.md +44 -0
  18. data/doc/Blacklight-3.6-release-notes-and-upgrade-guide.md +25 -0
  19. data/doc/Blacklight-3.7-release-notes-and-upgrade-guide.md +80 -0
  20. data/doc/Blacklight-3.8-release-notes-and-upgrade-guide.md +11 -0
  21. data/doc/Blacklight-4.0-release-notes-and-upgrade-guide.md +135 -0
  22. data/doc/Blacklight-4.1-release-notes-and-upgrade-guide.md +17 -0
  23. data/doc/Blacklight-4.2-release-notes-and-upgrade-guide.md +25 -0
  24. data/doc/Blacklight-4.3-release-notes-and-upgrade-guide.md +21 -0
  25. data/doc/Blacklight-4.4-release-notes-and-upgrade-guide.md +41 -0
  26. data/doc/Blacklight-Add-ons.md +28 -0
  27. data/doc/Blacklight-configuration.md +411 -0
  28. data/doc/Blacklight-on-Heroku.md +135 -0
  29. data/doc/Code4Lib-2014.md +48 -0
  30. data/doc/Community-principles.md +44 -0
  31. data/doc/Configuring-and-Customizing-Blacklight.md +271 -0
  32. data/doc/Configuring-rails-routes.md +13 -0
  33. data/doc/Contributing-to-Blacklight.md +25 -0
  34. data/doc/Examples.md +94 -0
  35. data/doc/Extending-or-Modifying-Blacklight-Search-Behavior.md +141 -0
  36. data/doc/FAQs.md +1 -0
  37. data/doc/Home.md +80 -0
  38. data/doc/How-to-release-a-version.md +29 -0
  39. data/doc/Indexing-your-data-into-solr.md +32 -0
  40. data/doc/Integration-with-Rails-Footnotes.md +20 -0
  41. data/doc/Internationalization.md +32 -0
  42. data/doc/JSON-API.md +17 -0
  43. data/doc/Pagination.md +51 -0
  44. data/doc/Providing-your-own-view-templates.md +109 -0
  45. data/doc/Quickstart.md +115 -0
  46. data/doc/README_SOLR.md +245 -0
  47. data/doc/Release-Notes-And-Upgrade-Guides.md +20 -0
  48. data/doc/Roadmap.md +43 -0
  49. data/doc/Sunspot-for-indexing.md +46 -0
  50. data/doc/Theming.md +64 -0
  51. data/doc/User-Authentication.md +60 -0
  52. data/doc/testing.md +57 -0
  53. data/lib/blacklight.rb +6 -0
  54. data/lib/blacklight/base.rb +2 -0
  55. data/lib/blacklight/catalog.rb +4 -3
  56. data/lib/blacklight/catalog/search_context.rb +8 -1
  57. data/lib/blacklight/configurable.rb +1 -2
  58. data/lib/blacklight/solr/document.rb +2 -1
  59. data/lib/blacklight/solr_helper.rb +8 -0
  60. data/lib/blacklight/user.rb +7 -2
  61. data/lib/blacklight/utils.rb +9 -1
  62. data/lib/generators/blacklight/templates/catalog_controller.rb +1 -4
  63. data/spec/helpers/blacklight_helper_spec.rb +84 -9
  64. data/spec/helpers/hash_as_hidden_fields_spec.rb +1 -1
  65. data/spec/lib/blacklight_spec.rb +6 -0
  66. data/spec/lib/blacklight_user_spec.rb +4 -0
  67. data/spec/lib/solr_helper_spec.rb +8 -6
  68. data/spec/lib/utils_spec.rb +35 -5
  69. data/spec/views/catalog/_paginate_compact.html.erb_spec.rb +1 -1
  70. metadata +49 -8
@@ -0,0 +1,13 @@
1
+ If your solr ids happen to have dots in them, Rails is going interpret the dots as the separator between the file name and the file exension, and your documents won't be displayed on the show view. In order to fix that you can override the default routes like this:
2
+
3
+ ```ruby
4
+ ALLOW_DOTS ||= /[a-zA-Z0-9_.:]+/
5
+ MyApp::Application.routes.draw do
6
+ root :to => "catalog#index"
7
+ ...
8
+ resources :catalog, :only => [:show, :update], :constraints => { :id => ALLOW_DOTS, :format => false }
9
+ Blacklight::Routes.new(self, {}).catalog
10
+ end
11
+ ```
12
+
13
+ you must put the line defining the route with the constraints before you call Blacklight::Routes because the first route that matches is the one that will be used.
@@ -0,0 +1,25 @@
1
+ # Contributing to Blacklight
2
+ Blacklight is a collaborative open source project by developers at various institutions, which we each work on largely motivated by our own local institutions' needs. We work on the shared project together so we can benefit from each other's code, but most developers primary priorities are to their own local development. In this it is like many such projects.
3
+
4
+ The Blacklight developers do want to create a product that is easy for newcomers to install and get started with -- both as a service to the community and in the interests of our own institutions in creating a sustainable project and product that continue to thrive through personnel changes. However, the developers may not always have time to find or fix bugs that may be affecting you, or lead you through every detail of getting Blacklight to work for you.
5
+
6
+ But we do try when we can -- please don't be scared to ask a question on the [[Blacklight mailing list|http://groups.google.com/group/blacklight-development]], just don't be shocked if we can't always give you the answer you want. We always welcome patch submissions; and we are always excited to hear about what others are doing with Blacklight. We're also always looking for more committers, although we usually like to see a patch or two before considering granting committer status.
7
+
8
+ If you follow this short guide, it will make it much easier for the community to review your changes, and the core team to get them included in the next release. If you are new to Git, be sure to read Github's (really good) [[step-by-step directions|http://help.github.com/fork-a-repo/]] for contributing to projects. If you want a basic introduction to git, check out [[Git Reference|http://gitref.org/]].
9
+
10
+ We also encourage a lot of peripheral functionality -- especially for features that may not be used by most implementations, as the Blacklight install base has a wide range of users -- to consider developing stand-alone, optional [[Blacklight add-ons]].
11
+
12
+ ## Adding a ticket
13
+ Let us know you're interested in working on a feature by filing a ticket in our [[issue tracker|https://github.com/projectblacklight/blacklight/issues]].
14
+
15
+ ## Making Your Changes
16
+
17
+ * Fork the project (Github has really good step-by-step directions
18
+ * Start a feature/bugfix branch
19
+ * Commit and push until you are happy with your contribution
20
+ * Make sure to add tests for it. This is important so we don't break it in a future version unintentionally.
21
+ * After making your changes, be sure to run the [[Blacklight rspec and cucumber tests|Testing]] to make sure everything works.
22
+ * Submit your change as a [[Pull Request|http://help.github.com/pull-requests/]].
23
+
24
+ ## Support
25
+ If you are interested in working on the Blacklight plugin, but want guidance or support, please send an email to our [[Blacklight-development mailing list|http://groups.google.com/group/blacklight-development]] and we'll be glad to help.
data/doc/Examples.md ADDED
@@ -0,0 +1,94 @@
1
+ You can see a demonstration of the generic Blacklight plugin at http://demo.projectblacklight.org
2
+
3
+ Blacklight 5.x demo site
4
+ http://bootstrap3.demo.projectblacklight.org
5
+
6
+ Agriculture Network Information Center
7
+ http://www.agnic.org/search
8
+
9
+ American Legislative and Issue Campaign Exchange (ALICE)
10
+ http://alicelaw.org/
11
+
12
+ Bibliothèque Clermont Université
13
+ http://195.221.120.231
14
+
15
+ Columbia University:
16
+
17
+ * CLIO - Unified search and discovery - http://clio.columbia.edu
18
+ * Academic Commons - Institutional Repository - http://academiccommons.columbia.edu
19
+ * Human Rights Web Archive - http://hrwa.cul.columbia.edu
20
+ * Special Collection Site - Lindquist - http://lindquist.cul.columbia.edu
21
+
22
+ Cornell University
23
+ http://newcatalog.library.cornell.edu/
24
+
25
+ Danmarks Tekniske Universitet (Technical University of Denmark) - DTU Findit - http://findit.dtu.dk
26
+
27
+ Indiana University Libraries
28
+ * IUCAT library catalog - http://iucat.iu.edu/
29
+ * Digital Collections Search - http://webapp1.dlib.indiana.edu/dcs/
30
+
31
+ Johns Hopkins University Libraries (Catalyst)
32
+ http://catalyst.library.jhu.edu
33
+
34
+ Lowcountry Digital Library (College of Charleston):
35
+ * http://lcdl.library.cofc.edu/
36
+ * Code4Lib Article - http://journal.code4lib.org/articles/8327
37
+
38
+ NCSU Libraries' Digital Collections: Rare and Unique Materials (This application superseded the Historical State application which was also a Blacklight application.)
39
+ http://d.lib.ncsu.edu/collections/
40
+
41
+ The New York Public Library
42
+
43
+ * Andre Studios 1930-1941 - http://andrestudios.nypl.org
44
+ * Prints & Photographs Online Catalog - http://wallachprintsandphotos.nypl.org/
45
+
46
+ Northwest Digital Archives
47
+ http://nwda.projectblacklight.org
48
+
49
+ Northwestern University Library Archival and Manuscript Collections
50
+ http://findingaids.library.northwestern.edu
51
+
52
+ NRM (Natural Resource Management) knowledge online
53
+ http://nrmonline.nrm.gov.au/
54
+
55
+ The Pennsylvania State University (Penn State)
56
+ https://scholarsphere.psu.edu/
57
+
58
+ Rock & Roll Hall of Fame
59
+ http://catalog.rockhall.com/
60
+
61
+ Stanford University
62
+ http://searchworks.stanford.edu
63
+
64
+ Tufts University
65
+ http://dl.tufts.edu
66
+
67
+ University of Virginia
68
+ http://search.lib.virginia.edu
69
+
70
+ University of Wisconsin-Madison
71
+ http://search.library.wisconsin.edu/
72
+
73
+ United States Holocaust Memorial Museum
74
+ http://collections.ushmm.org
75
+
76
+ WGBH Open Vault
77
+ http://openvault.wgbh.org
78
+
79
+ University of Hull:
80
+
81
+ * Institutional repository - http://hydra.hull.ac.uk
82
+ * Library catalogue - http://libsearch.hull.ac.uk/
83
+
84
+ The World Maritime University (using Koha ILS )
85
+ http://beacon.wmu.se
86
+
87
+ The UI component of the Hydra Framework - http://projecthydra.org
88
+
89
+
90
+
91
+
92
+ ## Media/Presentations
93
+
94
+ * ["Highly Relevant Search Result Ranking for Large Law Enforcement Information Sharing Systems"](http://www.lucidimagination.com/blog/2011/06/01/solr-and-law-enforcement-highly-relevant-results-can-be-a-crime/), presented by Ronald Mayer of Forensic Logic at Lucene Revolution 2011 - Blacklight was used to quickly provide a proof-of-concept on law enforcement data.
@@ -0,0 +1,141 @@
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/FAQs.md ADDED
@@ -0,0 +1 @@
1
+ Currently no FAQs are written. Feel free to add any.
data/doc/Home.md ADDED
@@ -0,0 +1,80 @@
1
+ #
2
+ [[https://github.com/projectblacklight/projectblacklight.github.com/raw/master/images/logo.png]]
3
+
4
+ ## Introduction
5
+
6
+ Blacklight is an open source, Ruby on Rails engine/gem that provides a discovery interface for [Apache Solr](http://lucene.apache.org/solr). Blacklight provides a basic user interface for searching a 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.
7
+
8
+ Some other features include:
9
+
10
+ * Stable URLs for search and record pages allow users to bookmark, share, and save search queries for later access
11
+ * Every Blacklight search provides RSS and Atom Responses of search results
12
+ * 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.
13
+ * Blacklight supports OpenSearch, a collection of simple formats for the sharing of search results.
14
+ * Faceted searching
15
+ * Search queries can be targeted at specific sets of fields
16
+ * Results sorting
17
+ * Tools for exporting records to Refworks or Endnote, sending records via Email or SMS, or as a formatted citation.
18
+
19
+ A [demo application](http://demo.projectblacklight.org) uses the latest version of Blacklight to display a basic library catalog.
20
+
21
+ > NOTE: This wiki provides developer documentation for the latest Blacklight release. For documentation of older releases, see the end of this page.
22
+
23
+ ## Getting Started
24
+ * [[Quickstart Guide|Quickstart]]
25
+ * [[Site Search|http://projectblacklight.org/search.html]]
26
+ * [[Demo|http://demo.projectblacklight.org]]
27
+ * [[Example installations|Examples]]
28
+ * [[Release Notes And Upgrade Guides]]
29
+
30
+ ## Developing your application
31
+ * [[Blacklight Configuration]]: Search results, facets, query fields
32
+ * [[Providing your own view templates]]: Overriding the out-of-the-box Blacklight templates the Rails way.
33
+ * [[Theming]]: Overriding the Blacklight CSS
34
+ * [[User Authentication]]: Connecting Blacklight with an existing Authentication system
35
+ * [[Extending or Modifying Blacklight Search Behavior]] How to change the way the Blacklight discovery feature works.
36
+ * [[Internationalization]]: Translating (or simply customizing) the Blacklight copy
37
+ * [[Common Blacklight Patterns]]
38
+ * [[JSON API]]
39
+ * [[Configuring Rails Routes]]
40
+ * [[Indexing your data into Solr]]
41
+ * [[Additional Blacklight-specific Solr documentation|README_SOLR]]
42
+ * [[Blacklight on Heroku]]
43
+ * [[Pagination]]: Advice on how to customize pagination with Kaminari
44
+ * [[Blacklight Plugins/Addons|Blacklight-Add-ons]]
45
+
46
+
47
+ ## Support
48
+ 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.
49
+
50
+ 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.
51
+
52
+ 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]].
53
+
54
+ * [[Bug Tracker|https://github.com/projectblacklight/blacklight/issues/]]
55
+ * [[Mailing List|http://groups.google.com/group/blacklight-development]]
56
+ * [![Build Status](https://travis-ci.org/projectblacklight/blacklight.png?branch=master)](https://travis-ci.org/projectblacklight/blacklight)
57
+
58
+ ## Contributing to Blacklight
59
+
60
+ * [[Contributing to Blacklight]]
61
+ * [[Community Principles]]
62
+ * [[How to release a version]]
63
+ * [[Testing]]
64
+
65
+ ## Releases
66
+ Blacklight releases are published on the [[Rubygems.org blacklight project|https://rubygems.org/gems/blacklight]].
67
+
68
+ For a list of features and bugfixes in Blacklight releases, see the [[Release announcements|Release Notes And Upgrade Guides]] on this wiki.
69
+
70
+ ### Older Documentation
71
+ 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:
72
+
73
+ * [[Home]]
74
+ * [[Blacklight 3.x|https://github.com/projectblacklight/blacklight/tree/release-3.8/doc]]
75
+ * [[Blacklight 3.0 or 3.1|https://github.com/projectblacklight/blacklight/tree/release-3.1/doc]]
76
+ * [[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:
77
+ * [[Blacklight 2.7|https://github.com/projectblacklight/blacklight/tree/v2.7.0/doc]]
78
+ * [[Blacklight 2.6|https://github.com/projectblacklight/blacklight/tree/v2.6.0/doc]]
79
+ * [[Blacklight 2.5|https://github.com/projectblacklight/blacklight/tree/v2.5.0/doc]]
80
+ * [[Blacklight 2.4|https://github.com/projectblacklight/blacklight/tree/v2.4.2/doc]]
@@ -0,0 +1,29 @@
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.
17
+
18
+ 1. Prepare announcement
19
+ * Include URL to GitHub closed issues for version
20
+ * 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.
21
+ * Include URL to the Github wiki [[Release Notes And Upgrade Guides]].
22
+
23
+ 1. Release the gem
24
+ ```bash
25
+ $ rake release
26
+ ```
27
+
28
+ 1. Announce
29
+ * Write emails announcing the release to Blacklight Development
@@ -0,0 +1,32 @@
1
+ Blacklight uses Solr as its data index. Blacklight is agnostic as to how that Solr index gets populated. Many Blacklight contributors work in university libraries and have to deal with library data in the MARC format. The Blacklight out-of-the-box demo and test suite is geared towards that use case.
2
+
3
+ ## Common Patterns
4
+
5
+ If you're not dealing with MARC records, you might do something like the following:
6
+
7
+ class MyModel < ActiveRecord::Base
8
+ after_save :index_record
9
+ before_destroy :remove_from_index
10
+
11
+ attr_accessible :field_i_want_to_index
12
+
13
+ def to_solr
14
+ # *_texts here is a dynamic field type specified in solrconfig.xml
15
+ {'id' => id,
16
+ 'field_i_want_to_index_texts' => field_i_want_to_index}
17
+ end
18
+
19
+ def index_record
20
+ SolrService.add(self.to_solr)
21
+ SolrService.commit
22
+ end
23
+
24
+ def remove_from_index
25
+ SolrService.delete_by_id(self.id)
26
+ SolrService.commit
27
+ end
28
+ end
29
+
30
+ ## What’s the relationship between Blacklight and SolrMarc?
31
+
32
+ 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.
@@ -0,0 +1,20 @@
1
+ [[Rails Footnotes|https://github.com/josevalim/rails-footnotes]] is a helpful plugin that displays footnotes in your application for easy debugging, such as sessions, request parameters, cookies, filter chain, routes, queries, etc. Installing Rails Footnotes is very easy, just add this to your Gemfile:
2
+ ```ruby
3
+ gem 'rails-footnotes', '>= 3.7', :group => :development
4
+ ```
5
+
6
+ And add something like this to config/initializers/footnotes.rb to run the Footnotes plugin:
7
+ ```ruby
8
+ if defined?(Footnotes) && Rails.env.development?
9
+ Footnotes.run!
10
+ end
11
+ ```
12
+
13
+ To add RSolr debugging information to the footnotes panel, you can use the [[RSolr Footnotes|https://github.com/cbeer/rsolr-footnotes]] gem by adding this to your Gemfile:
14
+ ```ruby
15
+ gem "rsolr-footnotes", :group => :development
16
+ ```
17
+
18
+ RSolr footnotes will capture every solr request with basic performance information and provide a link back to the Solr request URL.
19
+
20
+ [[https://github.com/projectblacklight/projectblacklight.github.com/raw/master/images/rsolr_footnotes_example.png|frame|alt=Example of RSolr Footnotes in the Blacklight Demo App]]