blacklight 3.8.2 → 4.0.0.pre6

data/doc/README_SOLR.md

@@ -1,245 +0,0 @@
-#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

@@ -1,14 +0,0 @@
-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)

data/doc/Sunspot-for-indexing.md

@@ -1,46 +0,0 @@
-If you have a Rails application as your data store, you may look to [Sunspot](http://outoftime.github.com/sunspot/) to help index your ActiveRecord models. Sunspot provides a nice DSL that makes it easy to index your models and associations. There is one gotcha, though, for using Sunspot with Blacklight. Both Sunspot and Blacklight expect the Solr uniqueKey to be in the "id" field. Sunspot will use the class of your model plus the primary key of that instance as the value for the id field. So a value for the id field may look like this: "Resource 123". 
-
-When a Sunspot-indexed Solr is used with Blacklight your model names and primary keys are exposed in your URLs. You may want to use a different value as your id value for Blacklight to use for document recall and URLs. For instance you want to use a unique filename as your id value for Blacklight.  
-
-You can use something like the following monkeypatch of Sunspot (1.2) by placing it in config/initializers/sunspot_monkeypatch_id.rb. It takes the value of the id field that Sunspot creates (Resource 123) and places it in the resource_id_ss field. It then overwrites the id value with the value from the filename field. The second part then takes a Solr hit and reverses it so that Sunspot can retrieve your models.
-
-```ruby
-     # for using a different value for the id field of your Solr documents
-     Sunspot::Indexer.module_eval do
-       alias :old_prepare :prepare
-       def prepare(model)
-         document = old_prepare(model)
-         document.fields_by_name(:resource_id_ss).first.value = document.fields_by_name(:id).first.value
-         if !document.fields_by_name(:filename).blank? and !document.fields_by_name(:filename).first.blank?
-            document.fields_by_name(:id).first.value = document.fields_by_name(:filename).first.value
-         end
-         document
-       end
-
-       alias :old_remove :remove  
-       def remove(*models)
-         @connection.delete_by_id(
-           models.map do |model| 
-             prepare(model).fields_by_name(:id).first.value
-           end
-         )
-       end
-
-     end
-
-     # to allow searching with Sunspot's DSL as well to retrieve your models
-     class Sunspot::Search::Hit
-       def initialize(raw_hit, highlights, search) 
-         raw_hit['id'] = raw_hit['resource_id_ss']
-         @class_name, @primary_key = *raw_hit['id'].match(/([^ ]+) (.+)/)[1..2]
-         @score = raw_hit['score']
-         @search = search
-         @stored_values = raw_hit
-         @stored_cache = {}
-         @highlights = highlights
-       end
-     end
-```
-
-
-

data/doc/User-Authentication.md

@@ -1,60 +0,0 @@
-Blacklight does not require user authentication, however, if included, Blacklight can provide additional features for users ([[Bookmarks]], [[Saved Searches]], etc). Because of the wide range of institutional needs and capabilities, Blacklight does not require a specific user authentication provider. 
-
-## Installing with Devise
-
-If you are rolling your own user authentication system, we highly recommend [[Devise|https://github.com/plataformatec/devise]], an extremely flexible authentication solution that is relatively straightforward. For directions to install the Blacklight gem using devise, see the [[Quickstart]].
-
-## Install and Use (with a custom user authentication system)
-
-Create a new rails 3 application
-```bash
-$ rails new my_app
-```
-
-Add blacklight to your gem file 
-```bash
-edit ./my_app/Gemfile
-```
-```ruby.
-# Append this line to the end of the file:
-gem 'blacklight'
-```
-
-```bash
-$ bundle install
-```
-
-If you have a `User` model already, the Blacklight generator will connect to it automatically during installation.  However, you will need to make sure the following named routes are included in your /config/routes.rb file:
-
-```ruby
-  match 'your_login',          :to => 'Your User Session Controller # Log in action',       :as => 'new_user_session'
-  match 'your_logout',         :to => 'Your User Session Controller # Log Out action',      :as => 'destroy_user_session'
-  match 'your_account_page',   :to => 'Your User Session Controller # Account edit action', :as => 'edit_user_registration'
-```
-
-One blacklight view partial uses `#to_s` on your user model to get a user-displayable account name/identifier for the currently logged in account, so you probably want to have such a method. 
-
-Finally, you will need to make sure the following methods are available both on controllers and as helpers:
-
-* `current_user`   - Which should return an ActiveRecord-based user object that include Blacklight::User
-* `user_session`   - Which are included in your /config/routes.rb file:
-
-Optionally,
-* `guest_user` -  Which should return an ActiveRecord-based temporary guest user object available across the current user session.
-* `current_or_guest_user` - Which should return the `current_user`, if available, or `guest_user`. If you don't provide this method, a stub method (that just returns `current_user`) will be provided for you.
-
-If you are supporting guest users, if a guest user logs in, you should call `#transfer_guest_user_actions_to_current_user` to move any persisted data to the permanent user.
-
-> The `devise-guests` gem implements the `guest_user`, `current_or_guest_user` and callbacks for Blacklight applications using devise. It may be a useful reference for rolling your own functionality. See [DeviseGuests::Controllers::Helpers](https://github.com/cbeer/devise-guests/blob/master/lib/devise-guests/controllers/helpers.rb)
-
-Once these are in place, you can run the Blacklight Installation Generator:
-
-```bash
-$ rails generate blacklight [MODEL NAME]
-```
-Where model name is the name of your user model.
-
-Execute your migrations, and you should be good to go.
-```bash
-$ rake db:migrate
-```

data/doc/testing.md

@@ -1,115 +0,0 @@
-## Using Blacklight source checkout as gem for development
-
-
-The ordinary install instructions install the BL gem (which is not
-full source code) in wherever your system installs gems. 
-
-Sometimes, especially for development, it's useful to check out
-a complete copy of the blacklight source code, and link your app
-to that as a 'gem' instead. 
-
-Checkout the code:
-
-    $ git clone git@github.com:projectblacklight/blacklight.git  
-
-
-## Automatically generate a test application (and run the tests)
-Blacklight comes with a bash script you can use to create a complete test application.  It supports Ruby 1.8.7, Ruby 1.9.2+, and JRuby 1.6.2.
-
-Requirements:
-
-  * rvm  - (https://rvm.beginrescueend.com/)
-  * Java (1.5 or above)
-
-From the root directory of your git checkout:
-
-    $ ./test_support/bin/test.sh 1.8.7  
-
-This bash script will create a fresh application in tmp/test_app -  Inside this test application it will run a bundle install, execute required generators, run migrations, configure the test environment, install a jetty server with test data, and execute all of blacklight's rspec and cucumber tests.  
-
-Subsequent calls to this script will overwrite the test application. 
-
-## Manually Installing a test/stub application 
-
-1. Create a new rails 3 application
-
-         $ rails new test-app      
-         $ cd my_app
-
-    Rails automatically created an `index.html` file; Blacklight will provide a default `root` route, so you probably want to remove it:
-
-         $ rm public/index.html
-
-
-2. In your local app's Gemfile, simply specify that it should find
-the Blacklight gem at this source checkout location:
-
-        gem 'blacklight', :path=>"./relative/path/to/blacklight_checkout"
-
-    You can have the blacklight source checkout anywhere you want, referred to by absolute or relative path. You can have it inside your local app's directory if you want, or you can have it outside using a relative path beginning with "../".  If you have it inside your app's root, you can even use 'git submodule' techniques to link your app to a particular
-git commit, like some of us did in Rails2 Blacklight. (But you probably don't want it in your local apps ./vendor/plugins, that'll likely confuse Rails, since it's already being referred to in your Gemfile). 
-
-3. update the bundle
-
-        $ bundle install
-
-
-3. You also need to include some gems in your test app's Gemfile needed for running our tests:
-
-        group :development, :test do 
-          gem "rspec"
-          gem "rspec-rails"    
-          gem "cucumber-rails"
-          gem "database_cleaner"  
-          gem "capybara"
-          gem "webrat"
-          gem "jettywrapper"
-        end
-
-3. And some gems for using sass in the asset pipeline, inside group :assets that's already there in a rails 3.1 app, add:
-
-         group :assets do
-            gem 'therubyracer'  # not needed if you are on Windows or OSX where a JS runtime can already be found
-         end
-
-
-       
-
-3. Run the cucumber generator:
-
-        rails g cucumber:install
-
-
-3. Install blacklight using Devise for user authentication: 
-
-        $ gem install devise
-        $ rails generate blacklight --devise
-
-    If you would like to integrate with an existing user authentication provider, see [[User Authentication]].
-
-4. Run your database migrations
-
-        $ rake db:migrate
-
-
-5. You need to install a jetty/solr with test data for testing. You can do that like this (from your stub app home directory):
-
-        $  rails generate blacklight:jetty test_jetty -e test
-        $  rake solr:marc:index_test_data RAILS_ENV=test
-
-
-## Running the Tests
-Now use some rake tasks that come with Blacklight to actually run the tests. Run these from your stub app:
-
-  * `rake blacklight:spec:with_solr`
-  * `rake blacklight:cucumber:with_solr` 
-
-You can also run the tests without starting the test_jetty (however, tests will fail unless you start it yourself):
-
-  * `rake blacklight:cucumber`
-  * `rake blacklight:spec`
-
-The standard rails tasks for cucumber/rspec are all included with 
-    blacklight: prefix, and should work as expected, but using
-    specs/features defined in BL plugin instead of in your local
-    app. (Not every variant has a :with_solr yet).