blacklight 3.8.1 → 3.8.2

data/doc/Quickstart.md

@@ -0,0 +1,116 @@
+Blacklight is a Ruby on Rails Engine plugin, meaning it provides a small application that runs inside an existing Ruby on Rails project.  For notes on upgrading Blacklight, check out our [[Release Notes And Upgrade Guides]] index.
+
+## Pre-requisites
+ * Ruby 1.9 or higher (consider using [[RVM|https://rvm.beginrescueend.com/rvm/install/]] or [[RBEnv|http://rbenv.org/]] to manage your Ruby version). 
+ * Java 1.5 or higher (in order to run solr under a java servlet container)
+ * **For Windows users**: You may want to use [RailsInstaller](http://railsinstaller.org/) to get a Ruby on Rails environment.
+
+> NOTE: We run our continuous integration tests against Ruby 1.9.3, Ruby 1.8.7, JRuby and REE using the latest release of Rails, although we highly recommend using Ruby 1.9 and Rails 3.2.
+
+In addition, you should have the Bundler and Rails ruby gems installed:
+
+```bash
+$ gem install bundler
+$ gem install rails
+```
+
+## Install and Use
+
+1. Create a new rails 3 application
+
+    ```bash
+    $ rails new my_app      
+    #      create  
+    #      create  README
+    #      create  Rakefile
+    #      create  config.ru
+    #      create  .gitignore
+    #      create  Gemfile
+    #      [...]
+
+    $ cd my_app
+    ```
+
+    Rails automatically created an `public/index.html` file. However, Blacklight will provide a default `root` route for your application, so you probably want to remove it:
+
+    ```bash
+    $ rm public/index.html
+    ```
+
+2. Append this line to your application's `Gemfile`
+
+    ```ruby
+    gem 'blacklight'
+    ```
+
+    Especially if you are running on Linux, you may have to add `gem 'therubyracer'` to your gemfile, to get a Javascript runtime needed by the asset pipeline. 
+
+    then, update the bundle
+
+    ```bash
+    $ bundle install
+    ```
+
+3. Install blacklight using Devise for user authentication: 
+
+    ```bash
+    $ gem install devise
+    $ rails generate blacklight --devise
+    ```
+    If you would prefer to integrate with an alternative user authentication provider, see the [[User Authentication]] documentation. You can also install with no support for logged in users simply by omitting the devise install, and generating blacklight with `rails generate blacklight` (no --devise argument).
+
+4. Run your database migrations to create Blacklight's database tables:
+
+    ```bash
+    $ rake db:migrate
+    ```
+
+5. You will need to install and configure Solr. You can install
+Blacklight's example Solr configuration (using the jetty servlet container) that is configured to work with
+the Blacklight defaults:
+
+    ```bash
+    $ rails generate blacklight:jetty
+    ```
+ 
+    Alternatively, you can also install your own copy of Solr or point Blacklight at an existing Solr server ( referred to in your `config/solr.yml`). The Blacklight
+configuration must match your Solr configuration. In addition, Blacklight has minor expectations about the Solr configuration and schemas. You can generate the Blacklight demonstration solrconfig and schema files using:
+
+    ```bash
+    $ rails generate blacklight:solr_conf path/to/output/directory/
+    ```
+  
+    **For Windows Users: ** This step will only work on *nix platforms. You can manually download and extract a tagged version of [blacklight-jetty](https://github.com/projectblacklight/blacklight-jetty/tags). After extracting the file, you need to update the `config/solr.yml` file to add a `jetty_path` key to your test environment, e.g.:
+
+    ```yaml
+    test: &test
+       url: http://localhost:8983/solr
+       jetty_path: C:\path\to\jetty 
+    ```
+
+
+6.  Make sure your Solr server is running. If you installed the Blacklight demo Solr/Jetty package, you can start the Jetty/Solr server using:
+
+    ```bash
+    $ java -jar jetty/start.jar &
+    ```
+
+6. Index some data. You can index test MARC records provided Blacklight running:
+
+    ```bash
+    $ rake solr:marc:index_test_data
+    ```
+
+7. Start up your application
+
+    ```bash
+    $ rails server
+    ```
+
+Visit the catalog at [[http://localhost:3000/catalog]]. You should see the Blacklight interface with 30 MARC records for testing. Additional MARC records are available from the [[blacklight-data|https://github.com/projectblacklight/blacklight-data]] repository. These can be ingested into Solr using SolrMarc, 
+
+```bash
+$ rake solr:marc:index MARC_FILE=(path to file)
+```
+
+See [[Configuring and Customizing Blacklight]] for information about how to customize the Blacklight user interface, search experience, and more.

data/doc/README.md

@@ -0,0 +1,77 @@
+#
+[[https://github.com/projectblacklight/projectblacklight.github.com/raw/master/images/logo.png]]
+
+## Introduction
+
+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 with a 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. 
+
+Some other features include:
+
+* Stable URLs for search and record pages allow users to bookmark, share, and save search queries for later access
+* Every Blacklight search provides RSS and Atom Responses of search results
+* 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.
+* Blacklight supports OpenSearch, a collection of simple formats for the sharing of search results.
+* Faceted searching
+* Search queries can be targeted at specific sets of fields
+* Results sorting
+* Tools for exporting records to Refworks or Endnote, sending records via Email or SMS, or as a formatted citation.
+
+A [demo application](http://demo.projectblacklight.org) uses the latest version of Blacklight to display a basic library catalog.
+
+> NOTE: This wiki provides developer documentation for the latest Blacklight release. For documentation of older releases, see the end of this page.
+
+## Getting Started
+* [[Quickstart Guide|Quickstart]]
+* [[Site Search|http://projectblacklight.org/search.html]]
+* [[Demo|http://demo.projectblacklight.org]]
+* [[Example installations|Examples]]
+* [[Release Notes And Upgrade Guides]]
+
+
+## Developing your application
+* [[Blacklight Configuration]]: Search results, facets, query fields
+* [[Providing your own view templates]]: Overriding the out-of-the-box Blacklight templates the Rails way.
+* [[User Authentication]]: Connecting Blacklight with an existing Authentication system
+* [[Extending or Modifying Blacklight Search Behavior]] How to change the way the Blacklight discovery feature works.
+* [[Internationalization]]: Translating (or simply customizing) the Blacklight copy
+* [[Common Blacklight Patterns]]
+* [[Indexing your data into Solr]]
+* [[Additional Blacklight-specific Solr documentation|README_SOLR]]
+* [[Blacklight on Heroku]]
+* [[Pagination]]: Advise on how to customize pagination with Kaminari
+
+
+## Support
+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.
+
+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. 
+
+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]].
+
+* [[Bug Tracker|https://github.com/projectblacklight/blacklight/issues/]]
+* [[Mailing List|http://groups.google.com/group/blacklight-development]]
+* [[Jenkins Continuous Integration|http://hudson.projectblacklight.org]]
+
+## Contributing to Blacklight
+
+* [[Contributing to Blacklight]]
+* [[Community Principles]]
+* [[How to release a version]]
+* [[Testing]]
+
+## Releases
+Blacklight releases are published on the [[Rubygems.org blacklight project|https://rubygems.org/gems/blacklight]].
+
+For a list of features and bugfixes in Blacklight releases, see the [[Release announcements|Release Notes And Upgrade Guides]] on this wiki.
+
+### Older Documentation
+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:
+
+* [[Home]]
+* [[Blacklight 3.x|https://github.com/projectblacklight/blacklight/tree/release-3.8/doc]]
+* [[Blacklight 3.0 or 3.1|https://github.com/projectblacklight/blacklight/tree/release-3.1/doc]]
+* [[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:
+    * [[Blacklight 2.7|https://github.com/projectblacklight/blacklight/tree/v2.7.0/doc]]
+    * [[Blacklight 2.6|https://github.com/projectblacklight/blacklight/tree/v2.6.0/doc]]
+    * [[Blacklight 2.5|https://github.com/projectblacklight/blacklight/tree/v2.5.0/doc]]
+    * [[Blacklight 2.4|https://github.com/projectblacklight/blacklight/tree/v2.4.2/doc]]

data/doc/README_SOLR.md

@@ -0,0 +1,245 @@
+#Solr in Blacklight
+
+##Setting up Solr
+
+Blacklight uses Solr as its "search engine". 
+More information about Solr is available at the Solr web site ( http://lucene.apache.org/solr/)
+
+There are three sections to this document:
+* Getting Solr
+* Configuring Solr
+  * schema.xml
+  * solrconfig.xml
+* SolrMARC
+
+### Getting Solr
+Blacklight distributes a pre-configured version of Solr (with the Jetty
+container) as [[blacklight-jetty|https://github.com/projectblacklight/blacklight-jetty/tags]].
+
+You can also use an existing Solr index (with some minor modifications).
+If you want to start from a new version of Solr, follow the directions from the [[Solr tutorial|http://lucene.apache.org/solr/tutorial.html]]
+
+You should now have a usable copy of Solr.
+
+### Configuring Solr
+####Solr Schema.xml
+
+Between the `schema.xml` and `solrconfig.xml` you can change and tune the search behavior following directions from the [[Solr wiki|http://wiki.apache.org/solr/]]. Solr comes with example schema and solrconfig files, which you can use as a starting point for configuring your local Solr application.
+
+Blacklight expects a uniqueKey field within your Solr index,
+traditionally called `id`. The name of the unique key field can be
+configured in your application's `SolrDocument`.
+
+##### Blacklight community "best practices"
+
+Solr uses a schema.xml file to define document fields (among other things). These fields store data for searching and for result display. You can find the example/solr/conf/schema.xml file in the Solr distribution you just downloaded and uncompressed.
+
+Documentation about the Solr schema.xml file is available at (http://wiki.apache.org/solr/SchemaXml).
+
+  The default schema.xml file comes with some preset fields made to work with
+  the example data. If you don't already have a schema.xml setup, we 
+  recommend using a simplified "fields" section like this:
+```xml  
+	<fields>
+		<field name="id" type="string" indexed="true" stored="true" required="true" />
+		<field name="text" type="text" indexed="true" stored="false" multiValued="true"/>
+		<field name="timestamp" type="date" indexed="true" stored="true" default="NOW" multiValued="false"/>
+		<field name="spell" type="textSpell" indexed="true" stored="true" multiValued="true"/>
+		<dynamicField name="*_i"  type="sint"    indexed="true"  stored="true"/>
+		<dynamicField name="*_s"  type="string"  indexed="true"  stored="true" multiValued="true"/>
+		<dynamicField name="*_l"  type="slong"   indexed="true"  stored="true"/>
+		<dynamicField name="*_t"  type="text"    indexed="true"  stored="true" multiValued="true"/>
+		<dynamicField name="*_b"  type="boolean" indexed="true"  stored="true"/>
+		<dynamicField name="*_f"  type="sfloat"  indexed="true"  stored="true"/>
+		<dynamicField name="*_d"  type="sdouble" indexed="true"  stored="true"/>
+		<dynamicField name="*_dt" type="date"    indexed="true"  stored="true"/>
+		<dynamicField name="random*" type="random" />
+		<dynamicField name="*_facet" type="string" indexed="true" stored="true" multiValued="true" />
+		<dynamicField name="*_display" type="string" indexed="false" stored="true" />
+	</fields>
+```        
+	
+  
+  Additionally, replace all of the tags after the "fields" section, and before 
+  the `</schema>` tag with this:
+```xml  
+	<uniqueKey>id</uniqueKey>
+	<defaultSearchField>text</defaultSearchField>
+	<solrQueryParser defaultOperator="OR"/>
+	<copyField source="*_facet" dest="text"/>
+```
+
+  Now you have a basic schema.xml file ready. Other fields can be specified, including a primary document title (`title_display`) and format (`format`), but these are easily configured in your application's `CatalogController`.
+
+  Fields that are "indexed" are searchable.
+
+  Fields that are "stored" are can be viewed/displayed from the Solr search 
+  results. 
+
+  The fields with asterisks ('*') in their names are "dynamic" fields. These 
+  allow you to create arbitrary tags at index time. 
+
+  The *_facet field can be used for creating your facets. When you index, 
+  simply define a field with _facet on the end:
+    category_facet
+
+  The *_display field can be used for storing text that doesn't need to be 
+  indexed. An example would be the raw MARC for a record's detail view:
+    raw_marc_display
+
+  For text that will be queried (and possibly displayed), use the *_t type 
+  field for tokenized text (text broken into pieces/words) or the *_s type 
+  for queries that should exactly match the field contents:
+    description_t
+    url_s
+
+  The Blacklight application is generic enough to work with any Solr schema, but to
+  manipulate the search results and single record displays, you'll need to know the 
+  stored fields in your indexed documents.
+
+  For more information, refer to the Solr documentation: 
+    http://wiki.apache.org/solr/SchemaXml
+
+
+#####solrconfig.xml
+
+Solr uses the solrconfig.xml file to define searching configurations, set cache options, etc. 
+You can find the examples/solr/conf/solrconfig.xml in the distribution directory you just uncompressed.
+
+Documentation about the solrconfig.xml file is available at (http://wiki.apache.org/solr/SolrConfigXml).
+
+Blacklight expects two request handlers to be defined -- one to handle
+general search requests and one to handle single-document lookup. The
+names of these request handlers are configurable, but are called
+"search" and "document" respectively, out of the box.
+
+
+#####Solr Search Request Handlers
+
+  When Blacklight does a collection search, it sends a request to a Solr 
+  request handler named "search". The most important settings in this handler 
+  definition are the "fl" param (field list) and the facet params.
+
+  The "fl" param specifies which fields are returned in a Solr response.
+  The facet related params set up the faceting mechanism.
+
+  Find out more about the basic params: 
+     http://wiki.apache.org/solr/DisMaxRequestHandler
+  
+  Find out more about the faceting params: 
+    http://wiki.apache.org/solr/SimpleFacetParameters
+
+
+######How the "fl" param works in Blacklight's request handlers
+
+  Blacklight comes with a set of "default" views for rendering each document 
+  in a search results page. This view simply loops through all of the fields 
+  returned in each document in the Solr response. The "fl" (field list) param
+  tells Solr which fields to include in the documents in the response ... 
+  and these are the fields rendered in the Blacklight default views.  
+  Thus, the fields you want rendered must be specified in "fl".  Note that 
+  only "stored" fields will be available;  if you want a field to be rendered 
+  in the result, it must be "stored" per the field definition in schema.xml.
+
+  The "fl" parameter definition in the "search" handler looks like this:
+  ```xml
+    <str name="fl">id,score,author_display,(....lots of other fields)</str>
+  ```  
+  You may also use an asterisk plus "score":
+  ```xml
+    <str name="fl">*,score</str>
+  ```  
+
+######How the facet params work in Blacklight's request handlers
+
+  In the search results view, Blacklight will look into the Solr response for 
+  facets. If you specify any facet.field params in your "search" handler, 
+  they will automatically get displayed in the facets list:
+  ```xml
+    <str name="facet.field">format</str>
+    <str name="facet.field">language_facet</str>
+  ```  
+
+
+#####Blacklight's "search" request handler: for search results
+
+  When Blacklight displays a list of search results, it uses a Solr request 
+  handler named "search." Thus, the field list (fl param) for the "search"
+  request handler should be tailored to what will be displayed in a search
+  results page.  Generally, this will not include fields containing a large
+  quantity of text.  The facet param should contain the facets to be 
+  displayed with the search results.
+  ```xml
+
+	<requestHandler name="search" class="solr.SearchHandler" >
+		<lst name="defaults">
+			<str name="defType">dismax</str>
+			<str name="echoParams">explicit</str>
+			<!-- list fields to be returned in the "fl" param -->
+			<str name="fl">*,score</str>
+			
+			<str name="facet">on</str>
+			<str name="facet.mincount">1</str>
+			<str name="facet.limit">10</str>
+			
+			<!-- list fields to be displayed as facets here. -->
+		    <str name="facet.field">format</str>
+		    <str name="facet.field">language_facet</str>
+			
+			<str name="q.alt">*:*</str>
+		</lst>
+	</requestHandler>
+   ```
+
+#####Blacklight's "document" request handler:  for a single record
+
+  When Blacklight displays a single record it uses a Solr request handler 
+  named "document".  The "document" handler doesn't necessarily need to be 
+  different than the "search" handler, but it can be used to control which 
+  fields are available to display a single document. In the example below, 
+  there is no faceting set (facets are not displayed with a single record) 
+  and the "rows" param is set to 1 (since there will only be a single record).
+  Also, the field list ("fl" param) could include fields containing large
+  text values if they are desired for record display. Is is acceptable to
+  include large amounts of data, because this handler should only be used 
+  to query for one document:
+
+	<requestHandler name="document" class="solr.SearchHandler">
+		<lst name="defaults">
+			<str name="echoParams">explicit</str>
+			<str name="fl">*</str>
+			<str name="rows">1</str>
+			<str name="q">{!raw f=id v=$id}</str>
+			<!-- use id=blah instead of q=id:blah -->
+		</lst>
+	</requestHandler>
+	
+  A Solr query for a single record might look like this:
+   http://(yourSolrBaseUrl)/solr/select?id=my_doc_id&qt=document
+
+
+####Blacklight Solr Schema and Solrconfig File Templates
+
+Blacklight provides schema.xml and solrconfig.xml files as starting points:
+
+  https://github.com/projectblacklight/blacklight-jetty/blob/master/solr/conf/schema.xml
+
+  https://github.com/projectblacklight/blacklight-jetty/blob/master/solr/conf/solrconfig.xml
+
+#SolrMARC:  from Marc data to Solr documents
+
+The SolrMARC project is designed to create a Solr index from raw MARC data.  
+It can be configured easily and used with the basic parsing and indexing 
+supplied.  It is also readily customized for a site's unique requirements.
+
+The project software and documentation is available at [[http://code.google.com/p/solrmarc]]
+
+Blacklight comes with an embedded SolrMarc, with some default config that matches the default Blacklight setup, and provides some rake tasks to easily index docs with SolrMarc according to your app's environment.  There is no need to manually install/configure SolrMarc yourself.  From your application's home directory simply run:
+```bash
+  rake solr:marc:index:info
+```
+to see options.  Run `rake solr:marc:index` to actually do indexing. Like all rake tasks, by default this will use your 'development' environment; add "RAILS_ENV=production" to instead index to the solr you've labelled production in your config/solr.yml file. 
+
+The solrmarc config files are in your app's config/SolrMarc directory, you can edit them there for local config. 
+
+If you'd like to use a different or more recent version of SolrMarc.jar, you can put it in your app at ./solr_marc/SolrMarc.jar, and the built-in rake tasks will use your local SolrMarc.jar instead of the one bundled with Blacklight. 

data/doc/Release-Notes-And-Upgrade-Guides.md

@@ -0,0 +1,14 @@
+This is for upgrade guides for each version.
+* [[Blacklight 3.8 Release Notes And Upgrade Guide]] (Nov 2, 2012)
+* [[Blacklight 3.7 Release Notes And Upgrade Guide]] (Sep 25, 2012)
+* [[Blacklight 3.6 Release Notes And Upgrade Guide]] (Sep 10, 2012)
+* [[Blacklight 3.5 Release Notes And Upgrade Guide]] (Jun 25, 2012)
+* [[Blacklight 3.4 Release Notes And Upgrade Guide]] (Apr 24, 2012)
+* [[Blacklight 3.3 Release Notes And Upgrade Guide]] (Mar 19, 2012)
+* [[Blacklight 3.2 Release Notes And Upgrade Guide]] (Dec 15, 2011)
+* [[Blacklight 3.1 Release Notes And Upgrade Guide]] (Sep 28, 2011)
+* [[Blacklight 3.0 Release Notes And Upgrade Guide]] (July 11, 2011)
+
+Unreleased
+
+* [[Blacklight 4.x Release Notes And Upgrade Guide]] (Nov X, 2012)