hydra 6.2.0.rc1 → 6.2.0

data/doc/Migrating-to-Hydra-6.2.md

@@ -0,0 +1,12 @@
+- `Rubydora::Repository#next_pid` has been superseded by `Rubydora::Repository#mint`.
+
+  Example:
+
+  ```ruby
+Nokogiri::XML(ActiveFedora::Base.connection_for_pid(0).next_pid(pid_opts)).at_xpath('//xmlns:pid').text
+```
+  should be:
+
+  ```ruby
+ActiveFedora::Base.connection_for_pid('0').mint(pid_opts)
+```

data/doc/Migration-Notes.md

@@ -0,0 +1,2 @@
+- [[Migrating to Hydra 6.2]]
+- [Migration notes for hydra-head releases](https://github.com/projecthydra/hydra-head/wiki/Migration-notes) (not Hydra gem)

data/doc/Models---Defining-a-Custom-Hydra-Model.textile

@@ -0,0 +1,198 @@
+h1. Models - Defining a Custom Hydra Model
+
+h2. General Introduction/Tutorial
+
+The "Getting Started Building Your Own Hydra Application":https://github.com/projecthydra/hydra-head/wiki/How-to-Get-Started tutorial includes a detailed section on defining a JournalArticle model.  Read that to get a sense of how to create a working Hydra Model.
+
+h2. Steps to Defining Your Model
+
+These steps assume you have gone through the basic Hydra app setup and are familiar with its general workings.  In order to create a custom model, you'll need to know how to create your OM terminology if you have a specific XML schema you want to use, or work with an existing OM terminology if one of the ones included with Hydra is sufficient.
+
+Additionally, you'll also need to know how to write rspec tests using fixtures, and have a working knowledge of the Fedora object relationship model.  For help with rspec tests, it's best use the code found in Hydra-Head as examples.  You can copy the tests for Hydra's models into your own application and modify them to test your particular model.  For more information about Fedora, see: "Fedora Wiki":https://wiki.duraspace.org/display/FEDORA/Home
+
+Here is a basic overview of the steps involved:
+
+# Pick your xml schema(s)
+# Create "fixtures" in XML for your schema(s)
+# Define or reuse OM terminologies & datastream classes for your XML
+# Write rspec tests for your catastream classes
+# Define the model
+# Write rspec tests for your model 
+# Decide what relationships your model will have & which predicates to use
+# Add relationship methods to your model
+# Define a rightsMetadata datastream for your objects
+# Setup depositor/owner permissions
+# Define additional default permissions if needed
+# Define delegate terms
+
+h2. rightsMetadata and Depositor/Owner Permissions
+
+Two steps are necessary in order to ensure that your controllers will be able to set the correct permissions on your assets.  If you don't follow these steps, users will be able to create objects but won't be able to edit them.
+
+Before reading this, make sure to read the page on "Hydra Access Controls":https://github.com/projecthydra/hydra-head/wiki/Access-Controls
+
+h3. Ensuring objects have a rightsMetadata datastream
+
+If you are adhering to the formal Hydra commonMetadata cModel which says that you must have a descMetadata datastream and a rightsMetadata datastream, you can put this line in your model:
+
+<pre>
+  # This model adheres to the formal Hydra commonMetadata cModel, meaning that it has a descMetadata datastream and a rightsMetadata datastream
+  include Hydra::ModelMixins::CommonMetadata
+</pre>
+
+If you are not adhering to the formal Hydra commonMetadata cModel and simply want to have a rightsMetadata datastream, declare the datastream directly in your Model
+
+<pre>
+  # Explicitly declaring rightsMetadata datastream
+  has_metadata :name => "rightsMetadata", :type => Hydra::RightsMetadata
+</pre>
+
+h3. Using Hydra::ModelMethods
+
+{Hydra::ModelMethods} will provide the {Hydra::ModelMethods#apply_depositor_metadata} method to your models.  This ensures that any controller operating on your models can grant a user edit permissions on the objects he or she creates.  When the user logs into the Hydra application, their login (ie. archivist1@example.com) will be added to the to the rightsMetadata datastream, giving them edit access.  
+
+You might want to override this with a method that including additional tasks more specific to your model.  If you decide to do this, the most important behavior to retain is adding +depositor_id+ to the asset's individual edit permissions if the asset has a rightsMetadata datastream.
+
+To add the method to your model, simply add this code to your model:
+<pre>
+  include Hydra::ModelMethods
+</pre>
+
+h3. Applying other default permissions
+
+Using Hydra's system of access controls, you can give newly created objects a default set of group permissions.  If you are using apply_depositor_metadata correctly, the depositor will have access to the item, but what if you want to grant other people access to the object based on their group membership?
+
+In that case, you can use the after_create hook in your model to run a method that applies some default permissions to your objects when they are created.  Either in the model code itself or in a separate file that you can include later, create a method called apply_default_permissions:
+
+<pre>
+  def apply_default_permissions
+    self.datastreams["rightsMetadata"].update_permissions( "group"=>{"archivist"=>"edit"} )
+    self.datastreams["rightsMetadata"].update_permissions( "group"=>{"reviewer"=>"edit"} )
+    self.datastreams["rightsMetadata"].update_permissions( "group"=>{"donor"=>"read"} )
+    self.save
+  end
+</pre>
+
+This method will grant edit privileges to the archivist and reviewer groups, while anyone in the donor group will have read access.  These groups and their members are defined in the config/role_mapper_*.yml files.  There will be one role mapper file for each of the Rails environments: development, test and production.  For example, if your role_mapper_production.yml file contains:
+
+<pre>
+archivist:
+  - archivist1@example.com
+donor:
+  - donor1@example.com
+reviewer:
+  - reviewer1@example.com
+researcher:
+  - researcher1@example.com
+patron:
+  - patron1@example.com
+</pre>
+
+The archivist1 and reviewer1 users will have edit access to all objects, by default, as well as donor1 who will have read access to all objects.  The patron1 user will not have any access unless it specifically granted via the Hydra web application.
+
+h3. Defining delegate terms
+
+The last step in creating your model will be to define delegate terms to each of the fields you want to use in your model.  Delegate terms allow your views and controllers to interact directly with the terms you've defined in OM.  You will need to have a delegate defined for every term you want to use in a view.  If you have terms in your OM definition that are not needed at the view level, then you won't need to create delegates for them; however, it is advisable to create delegates for any OM term that needs to be displayed or edited in any way.
+
+h2. Putting it all together
+
+Using these above examples and expanding upon the JournalArticle model that is used in the "content type example":https://github.com/projecthydra/hydra-head/wiki/Content-Type-Example:-Journal-Article, we can construct a more advanced Hydra model:
+
+<pre>
+class JournalArticle < ActiveFedora::Base
+  include Hydra::ModelMethods
+  include Hydra::ModelMixins::CommonMetadata
+  include ActiveFedora::Relationships
+
+  has_relationship "objects", :is_part_of, :inbound => true
+
+  after_create :apply_default_permissions
+  
+  has_metadata :name => "descMetadata",   :type => JournalArticleModsDatastream
+  has_metadata :name => "properties",     :type => MyApp::MyProperties
+
+  delegate :title,            :to=> :descMetadata, :unique=>"true"
+  delegate :abstract,         :to=> :descMetadata, :unique=>"true"
+  delegate :start_page,       :to=> :descMetadata
+  delegate :end_page,         :to=> :descMetadata
+  delegate :publication_date, :to=> :descMetadata
+  delegate :journal_title,    :to=> :descMetadata
+  delegate :journal_volume,   :to=> :descMetadata
+  delegate :journal_issue,    :to=> :descMetadata
+  delegate :depositor,        :to=> :properties
+
+  def apply_depositor_metadata(depositor_id)
+    self.depositor = depositor_id
+    super
+  end
+  
+  def apply_default_permissions
+    self.datastreams["rightsMetadata"].update_permissions( "group"=>{"archivist"=>"edit"} )
+    self.datastreams["rightsMetadata"].update_permissions( "group"=>{"reviewer"=>"edit"} )
+    self.datastreams["rightsMetadata"].update_permissions( "group"=>{"donor"=>"read"} )
+    self.save
+  end
+
+end
+</pre>
+
+h3. Explanation
+
+The first three include statements add in some basic features to our model.  Hydra::ModelMethods gives us the apply_depositor_metadata method and Hydra::ModelMixins::CommonMetadata gives us the rightsMetadata dastastream.  Remember that since we've included the mixin here, we don't need to define the datastream like we do the others.  The last include statement adds in ActiveFedora::Relationships which allows us to assert relationships with other objects.  This would be useful in a scenario where we have a JournalPage model defined and each journal page needs to claim it's parent object as a JournalArticle.  ActiveFedora lets us do this using the RELS-EXT datastream in Fedora.  Note that there is no JournalPage model defined anywhere.  If you want a model to assert a relationship to JournalArticle, then you're going to have to create it.  Once you have that model defined, then you can add the next line, has_relationship, which defines an inbound relationship where objects can assert a relationship to our JournalArtical model.
+
+The line after this uses our custom apply_default_permissions method.  Note that this is completely optional and not required in order for your Hydra models to work.  It's just an example of how you can use Rails hooks to add extra functionality to your models.  The apply_default_permissions method is defined at the bottom of the model.
+
+Next we define our datastreams.  We're using two, the JournalArticleModsDatastream that is defined in the "Content-Type-Example:-Journal-Article" example, and a second sample datastream that we're calling MyApp::MyProperties.  This assumes we have created an OM definition for this datastream.  We could use it here to store additional information about the object that does not belong in descMetadata.
+
+Following our datastreams is a section with our delegate definitions.  These map terms from each of our OM terminologies to fields in our model that will eventually translated to fields that we can interact with our views.  As you can see, there is a delegate for each term in descMetadata, which uses our JournalArticleModsDatastream, and one additional delegate for a term called "depositor" which is mapped to our properties datastream using the sample MyApp::MyProperties terminology.
+
+Finally, there are two methods.  The first, apply_depositor_metadata, overrides the method found in Hydra::ModelMethods with one additional step.  In this case, we're going to store the depositor_id in our properties datastream for later use.  After that, we want everything to proceed as normal and call "super" so that the rest of the method executes as it should according to Hydra's use.
+
+The last method is called using the after_create hook which applies some default permissions to our objects.
+
+h2. DRY it up
+
+One last little tweak.  If we wanted to share our custom methods with some of our other yet-to-be-define models, we could break out these methods to a separate file:
+
+<pre>
+module MyApp::MyModelMethods
+
+  def apply_depositor_metadata(depositor_id)
+    self.depositor = depositor_id
+    super
+  end
+  
+  def apply_default_permissions
+    self.datastreams["rightsMetadata"].update_permissions( "group"=>{"archivist"=>"edit"} )
+    self.datastreams["rightsMetadata"].update_permissions( "group"=>{"reviewer"=>"edit"} )
+    self.datastreams["rightsMetadata"].update_permissions( "group"=>{"donor"=>"read"} )
+    self.save
+  end
+
+end
+</pre>
+
+We then remove the method definitions from our model and our include statement then look like:
+
+<pre>
+  include Hydra::ModelMethods
+  include Hydra::ModelMixins::CommonMetadata
+  include ActiveFedora::Relationships
+  include MyApp::MyModelMethods
+</pre>
+
+We now have a module of code that can be included with our other custom models at will, just like we may include additional Hydra functions by adding additional include statements.
+
+h2. Other Topics
+
+h3. OM
+* namespaces
+* Indexing
+** index_as
+** suppressing fields
+** advanced indexing with custom solr schemas (:displayable and :searchable)
+* retrieving Terms & Values
+
+h2. More Information
+
+Further questions?  Ask the "hydra-tech list":http://groups.google.com/group/hydra-tech or join the freenode #projecthydra IRC channel.

data/doc/Rake-Tasks-in-Hydra-Head.textile

@@ -0,0 +1,40 @@
+This guide is known to work with hydra-head _version 6.0.0_.   
+_Please update this wiki to reflect any other versions that have been tested._
+
+h2. Getting info about the rake tasks from the command line
+
+<pre>rake -T</pre>
+
+To narrow down the output, use grep. For example:
+
+<pre>rake -T | grep hy</pre>
+
+
+h2. hydra:jetty Tasks
+
+_Prerequisite:_ You must have the following lines in your Gemfile 
+
+```ruby
+gem 'hydra-head'
+gem 'jettywrapper'
+```
+
+h3. The main tasks: load, start, stop
+
+<pre>
+  rake hydra:jetty:load                 # Copies the default SOLR config files and starts up the fedora instance.
+</pre>
+
+<pre>
+  rake jetty:start                      # Starts the bundled Hydra Testing Server
+  rake jetty:stop                       # Stops the bundled Hydra Testing Server
+</pre>
+
+h3. Subtasks: config, config_fedora, config_solr
+
+<pre>
+  rake hydra:jetty:config               # Copies the default Solr & Fedora configs into the bundled Hydra Testing Server
+  rake hydra:jetty:config_fedora        # Copies a custom fedora config for the bundled Hydra Testing Server
+  rake hydra:jetty:config_solr          # Copies the default SOLR config for the bundled Hydra Testing Server
+</pre>
+  

data/doc/Reference.textile

@@ -0,0 +1,19 @@
+See the github wikis for information targeted to developers: "http://github.com/projecthydra/hydra-head/wiki":http://github.com/projecthydra/hydra-head/wiki
+See the duraspace hydra wikis for information at the architecture level: "http://github.com/projecthydra/hydra-head/wiki":http://github.com/projecthydra/hydra-head/wiki
+Additionally, new adopters and potential adopters may find the pages here useful: "http://projecthydra.org/":http://projecthydra.org/
+
+Further questions? Ask the hydra-tech list or join the freenode #projecthydra IRC channel.
+
+h2. API Docs
+
+"ActiveFedora API Docs":http://rdoc.info/github/projecthydra/active_fedora
+"OM API Docs":http://rdoc.info/github/projecthydra/om
+"Solrizer-Fedora API Docs":http://rdoc.info/github/projecthydra/solrizer-fedora
+"Solrizer API Docs":http://rdoc.info/github/projecthydra/solrizer
+
+h2. Tutorials
+
+"ActiveFedora Console Tour":https://github.com/projecthydra/active_fedora/wiki/Getting-Started%3A-Console-Tour
+"OM-based NokogiriDatastreams":https://github.com/projecthydra/active_fedora/wiki/Nokogiri-Datastreams
+"Hydra-Head wiki pages":https://github.com/projecthydra/hydra-head/wiki/_pages
+

data/doc/Solr-Schema.rdoc

@@ -0,0 +1,44 @@
+== Dynamic Field Conventions
+The solr schema as found in schema.xml uses a convention with dynamic field names to expose the Solr properties of the field.  The following abbreviations are concatenated into the suffix:
+
+* Solr field type abbreviations
+  * t for text (language independent)
+  * te for English text
+  * s for string
+  * i for integer
+  * dt for date
+  * l for long
+  * db for double
+  * f for float
+  * b for boolean
+  * ll for location (think lat-lon)
+  * trie types are for faster range queries.  The t follows the solr field type abbreviation
+    * it for trie integer
+    * dtt for trie date
+    * lt for trie long
+    * dbt for trie double
+    * ft for trie float
+* Solr field properties abbreviations
+  * s if stored
+  * i if indexed
+  * m if multiValued
+  * v if termVectors (with termPositions and termOffsets also set to true)
+
+Examples:
+
+    <!-- text (_t...) -->
+    <dynamicField name="*_ti" type="text" stored="false" indexed="true" multiValued="false"/>
+    <dynamicField name="*_tim" type="text" stored="false" indexed="true" multiValued="true"/>
+    <dynamicField name="*_ts" type="text" stored="true" indexed="false" multiValued="false"/>
+    <dynamicField name="*_tsm" type="text" stored="true" indexed="false" multiValued="true"/>
+    <dynamicField name="*_tsi" type="text" stored="true" indexed="true" multiValued="false"/>
+    <dynamicField name="*_tsim" type="text" stored="true" indexed="true" multiValued="true"/>
+    <dynamicField name="*_tiv" type="text" stored="false" indexed="true" multiValued="false" termVectors="true" termPositions="true" termOffsets="true"/>
+    <dynamicField name="*_timv" type="text" stored="false" indexed="true" multiValued="true" termVectors="true" termPositions="true" termOffsets="true"/>
+    <dynamicField name="*_tsiv" type="text" stored="true" indexed="true" multiValued="false" termVectors="true" termPositions="true" termOffsets="true"/>
+    <dynamicField name="*_tsimv" type="text" stored="true" indexed="true" multiValued="true" termVectors="true" termPositions="true" termOffsets="true"/>
+
+    <!-- string (_s...) -->
+    <dynamicField name="*_si" type="string" stored="false" indexed="true" multiValued="false"/>
+    <dynamicField name="*_sim" type="string" stored="false" indexed="true" multiValued="true"/>
+    ...

data/doc/Tools-for-Developing-and-Testing-your-Application.textile

@@ -0,0 +1,69 @@
+h1. Tools for Developing and Testing your Application
+
+h2. Hydra-Jetty
+
+The Hydra project provides a copy of Jetty (a java web server) with Fedora and Solr pre-installed.  This is useful for running tests and for running your own code in your sandbox while you're actively working on your hydra head.
+
+The hydra-head gem provides a rake task for installing hydra-jetty
+
+<pre>
+  rails g hydra:jetty
+</pre>
+
+*Important*: To apply your application's solrconfig.xml and schema.xml to the copy of Solr in hydra-jetty, run this:
+
+<pre>
+  rake hydra:jetty:config
+</pre>
+
+Now you're ready to start jetty.  We've written a useful gem that gives you rake tasks for starting and stopping jetty.  Make sure you have jettywrapper in your Gemfile, available for both development and test environments:
+
+<pre>
+group :development, :test do
+  gem "jettywrapper"
+end
+</pre>
+
+If you just added it, then run <pre>bundle install</pre>
+
+Jettywrapper is now installed:
+
+*To start jetty*: <pre>rake jetty:start</pre>
+*To stop jetty*: <pre>rake jetty:stop</pre>
+
+For more information about using jettywrapper, see http://hudson.projecthydra.org/job/jettywrapper/Documentation/
+
+h2.  RSpec and Cucumber for Testing
+
+We STRONGLY recommend that you write tests for every local change you make.  This will allow you to ensure that upgrading the core code doesn't break any local changes you have made.
+
+A common question:  when should it be a cucumber feature rather than a spec?
+very basic rule:  if it's testing something created with view, use a cucumber feature to test.  If it's not created by view code, use a spec to test. 
+
+h4. RSpec for Functional Tests
+
+Most Ruby projects use either RSpec or Shoulda to write and run their Functional Tests.  We use RSpec for all of the Hydra software.
+
+To set up all the files you need to use rspec to test your Rails application, simply run the rspec generator.  This will create a directory called "spec" and put all of the necessary files into it.
+
+<pre>
+    rails g rspec:install
+</pre>
+
+h4. Cucumber to Test User Experience 
+
+If you will be writing cucumber tests, make sure you have the cucumber gem installed (in your test group in your Gemfile, then bundle install).
+
+<pre>
+group :test do 
+  gem 'rspec-rails', '>=2.9.0'
+  gem "cucumber-rails"
+  gem "database_cleaner"
+end
+</pre>
+
+(The database_cleaner gem is used by cucumber-rails when a database is involved.)
+
+Then run the cucumber generator.  This will create a directory called "features" and populate it with all the basic parts you need to run Cucumber tests on your Rails application.
+
+<pre>rails g cucumber:install</pre>

data/doc/YOUR-Hydra-Application---Initial-Modifications.textile

@@ -0,0 +1,357 @@
+h1. YOUR Hydra Application - Initial Modifications
+
+This document explains how to make two basic changes to your hydra rails application and how to write the appropriate tests for them.
+
+h2. What you will learn from this document:
+
+# How to Change the Home Page Text for Your Hydra Application
+# How to Change the Rails Application Name of Your Hydra Application
+# How to Change the Facets displayed for Limiting your Search
+# How to Override a Helper Method
+# How to Write a Simple Spec (an RSpec test)
+# How to Write a Simple Cucumber Feature
+
+Terminology note:  the Hydra and Blacklight gems are engines plugins for Rails applications. 
+
+h4. The Vanilla, Freshly Created Hydra Application
+
+By following the instructions of the "README":https://github.com/projecthydra/hydra-head/blob/master/README.textile, "Getting Started":https://github.com/projecthydra/hydra-head/wiki/How-to-Get-Started and so on, you should have gotten to a running rails application, with the default rails home page.
+
+h2. Making local changes to your Hydra Application
+
+In order to make it easy to get any new functionality added to the hydra stack (see "README":http://hudson.projecthydra.org/job/hydra-head-rails3-plugin/Documentation/file.README.html), while retaining your Hydra application's localizations, your local hydra application code should be set up to override the upstream Hydra stack code. 
+
+Luckily, rails engines has made this easy - the Hydra code is organized so your localizations are kept separate from the core hydra application code.
+
+Moreover, to ensure your localizations won't be broken by upgrading the Hydra core code, you should have tests for all your localizations.
+
+The two key points:
+
+<b>
+# always write tests for your local modifications
+# always change code at the app level, and never change anything in vendor/plugins.
+</b>
+
+h3. Easy Changes for Practice.
+
+h2. Changing the Home Text (also demonstrates Writing a Feature and Overriding a View)
+
+The home text is set in a view partial, so a cucumber feature is the most appropriate test (rather than an rspec test).
+
+h4. (1) Write the test.
+
+Create a file "features/home_page.feature" containing this:
+
+<pre>
+  Feature: Homepage
+    I want the home page to reflect localizations properly
+</pre>
+
+A test for checking the home text might be inserted like so:
+
+<pre>
+  Feature: Homepage
+    I want the home page to reflect localizations properly
+    
+    Scenario: home page text
+      When I am on the home page
+      Then I should not see "override"
+      And I should see "My Local Hydra App"
+</pre>
+
+h4. (2) Run the test - it should fail
+
+When you run this feature, the feature should run, but this test should fail (because you haven't changed anything yet.)
+
+Mine looked like this:
+
+<pre>
+$ rake cucumber:ok
+SOLRIZER: loading field name mappings from hydra-app/config/solr_mappings.yml
+resetting mappings for Solrizer::FieldMapper::Default
+/home/.rvm/rubies/ruby-1.9.3-p0/bin/ruby -S bundle exec cucumber  --profile default
+Using the default profile...
+Feature: Home page
+  I want the home page to reflect localizations properly
+
+  Scenario: home page text           # features/home_page.feature:4
+    When I am on the home page       # features/home_page.feature:5
+      Undefined step: "I am on the home page" (Cucumber::Undefined)
+      features/home_page.feature:5:in `When I am on the home page'
+    Then I should not see "override" # features/home_page.feature:6
+      Undefined step: "I should not see "override"" (Cucumber::Undefined)
+      features/home_page.feature:6:in `Then I should not see "override"'
+    And I should see "My Local Hydra App"        # features/home_page.feature:7
+      Undefined step: "I should see "My Local Hydra App"" (Cucumber::Undefined)
+      features/home_page.feature:7:in `And I should see "My Local Hydra App"'
+
+1 scenario (1 undefined)
+3 steps (3 undefined)
+0m0.003s
+
+You can implement step definitions for undefined steps with these snippets:
+
+When /^I am on the home page$/ do
+  pending # express the regexp above with the code you wish you had
+end
+
+Then /^I should not see "([^"]*)"$/ do |arg1|
+  pending # express the regexp above with the code you wish you had
+end
+
+Then /^I should see "([^"]*)"$/ do |arg1|
+  pending # express the regexp above with the code you wish you had
+end
+
+rake aborted!
+Command failed with status (1): [/home/.rvm/rubies/ruby-1.9.3-p0/b...]
+
+Tasks: TOP => cucumber:ok
+(See full trace by running task with --trace)
+</pre>
+
+If steps show as pending, you will need to define them.  If you are new to rails3, you might want to look at "http://aslakhellesoy.com/post/11055981222/the-training-wheels-came-off":http://aslakhellesoy.com/post/11055981222/the-training-wheels-came-off and/or "http://net.tutsplus.com/tutorials/ruby/ruby-for-newbies-testing-web-apps-with-capybara-and-cucumber/":http://net.tutsplus.com/tutorials/ruby/ruby-for-newbies-testing-web-apps-with-capybara-and-cucumber/
+
+Cucumber will load any files in the folder “features/step_definitions” for steps, so let’s create “my_steps.rb” file and add these steps:
+
+<pre>
+Given /^I am on the home page$/ do
+  visit "/"
+end
+ 
+Then /^I should not see "([^"]*)"$/ do |text|
+  page.should_not have_content text
+end
+
+Then /^I should see "([^"]*)"$/ do |text|
+  page.should have_content text
+end
+</pre>
+
+Now I get the following appropriate failure (as I still haven't changed any code):
+
+<pre>
+$ rake cucumber ok
+SOLRIZER: loading field name mappings from /hydra-app/config/solr_mappings.yml
+resetting mappings for Solrizer::FieldMapper::Default
+/home/.rvm/rubies/ruby-1.9.3-p0/bin/ruby -S bundle exec cucumber  --profile default
+Using the default profile...
+Feature: Home page
+  I want the home page to reflect localizations properly
+
+  Scenario: home page text           # features/home_page.feature:4
+    When I am on the home page       # features/step_definitions/basic_steps.rb:2
+    Then I should not see "override" # features/step_definitions/basic_steps.rb:6
+    And I should see "My Local Hydra App" # features/step_definitions/basic_steps.rb:10
+      expected there to be content "My Local Hydra App" in "Ruby on Rails: Welcome aboard\n      <snip>  " (RSpec::Expectations::ExpectationNotMetError)
+      ./features/step_definitions/basic_steps.rb:11:in `/^I should see "([^"]*)"$/'
+      features/home_page.feature:7:in `And I should see "My Local Hydra App"'
+
+Failing Scenarios:
+cucumber features/home_page.feature:4 # Scenario: home page text
+
+1 scenario (1 failed)
+3 steps (1 failed, 2 passed)
+0m0.199s
+rake aborted!
+</pre>
+
+h4. (3) Change the code
+
+We want to override the text on the home page locally, keeping our local changes separate from upstream changes to the plugins' code.
+
+The out-of-the-box default rails home page tells us what to do: 
+
+<pre>
+"Set up a default route and remove public/index.html
+</pre>
+
+We can tell from our app's config/routes.rb file that we already have a default route:
+
+<pre>
+MyHydraApp::Application.routes.draw do
+  Blacklight.add_routes(self)
+  HydraHead.add_routes(self)
+
+  root :to => "catalog#index"
+
+  devise_for :users
+</pre> 
+
+Remove public/index.html from our app ... and we now see the default Blacklight home page.  The text of the Blacklight home page informs us that we need to create 
+
+app/views/catalog/_home_text.html.erb
+
+to override the text in the home page.  So create that page, 
+Since the home text is set in @vendor/plugins/hydra-head/app/views/catalog/_home_text.html.erb@, we will override that code by creating a local @app/views/catalog/_home_text.html.erb@ file.  
+
+Our app/views/catalog/_home_text.html.erb might look like this
+
+<pre>
+<div class="home_text">
+  <h1>Welcome to My Local Hydra App</h1>
+</div>
+</pre>
+
+h4. (4) Run the test - it should now pass
+
+Now when you run the feature, it should pass.  If it doesn't, iterate until it does.
+
+<pre>
+$ rake cucumber:ok
+Using the default profile...
+Feature: Home page
+  I want the home page to reflect localizations properly
+
+  Scenario: home page text           # features/home_page.feature:4
+    When I am on the home page       # features/step_definitions/basic_steps.rb:2
+    Then I should not see "override" # features/step_definitions/basic_steps.rb:6
+    And I should see "My Local Hydra App" # features/step_definitions/basic_steps.rb:10
+
+1 scenario (1 passed)
+3 steps (3 passed)
+</pre>
+
+
+h2. Changing Application Title (also demonstrates Writing a Spec and Overriding a Helper Method)
+
+We want to change the application name (what displays as the html page's title).  This is set in a plugin's app/helper/application_helper.rb file.  Because it is set in a helper file, it is a good candidate for an rspec test (rather than a feature).
+
+h4. (1) Write the test.
+
+Since the application name is set in (vendor/plugins/hydra-head/)app/helpers/application_helper.rb, we need a spec to run against the application_helper file.
+
+Create a file "spec/helpers/application_helper_spec.rb".  A test for checking the application name might be inserted like so:
+
+<pre>
+  require File.expand_path('../../spec_helper', __FILE__)
+
+  describe ApplicationHelper do
+    include ApplicationHelper
+
+    context "overall UI methods" do
+      it "should get the local application name" do
+        application_name.should == "My Hydra"
+      end
+    end
+
+  end
+</pre>
+
+h4. (2) Run the test - it should fail
+
+When you run this spec, the spec should run, but this test should fail (because you haven't changed anything yet.)  Your output might look like this:
+
+<pre>
+$ rspec spec/helpers/application_helper_spec.rb 
+F
+
+Failures:
+
+  1) ApplicationHelper overall UI methods should get the local application name
+     Failure/Error: application_name.should == "My Hydra"
+     NameError:
+       undefined local variable or method `application_name' for #<RSpec::Core::ExampleGroup::Nested_1::Nested_1:0x007fe26887c6c8>
+     # ./spec/helpers/application_helper_spec.rb:9:in `block (3 levels) in <top (required)>'
+
+Finished in 0.02426 seconds
+1 example, 1 failure
+
+Failed examples:
+
+rspec ./spec/helpers/application_helper_spec.rb:8 # ApplicationHelper overall UI methods should get the local application name
+</pre>
+
+h4. (3) Change the code
+
+We want to override the application name locally, keeping our local changes separate from upstream changes to the plugins' code.
+
+Since the application name is set in vendor/plugins/hydra-head/app/helpers/application_helper.rb, we will override that code by putting a method of the same name in app/helpers/application_helper.rb.  The current app/helpers/application_helper.rb file may look like this:
+
+<pre>
+  # Methods added to this helper will be available to all templates in the application.
+  module ApplicationHelper
+  end
+</pre>
+
+Code for changing the application name might be inserted like so:
+
+<pre>
+  # Methods added to this helper will be available to all templates in the application.
+  module ApplicationHelper
+
+    def application_name
+      'My Hydra'
+    end
+
+  end
+</pre>
+
+h4. (4) Run the test - it should now pass
+
+Now when you run the spec, it should pass.  If it doesn't, iterate until it does.
+
+<pre>
+$ rspec spec/helpers/application_helper_spec.rb 
+.
+
+Finished in 0.00438 seconds
+1 example, 0 failures
+</pre>
+
+h2. Changing the Facets
+
+h4. (1) Write the test.
+
+Write the cucumber tests for the facets you want
+
+Create a file in your features directory called homepage_facets.feature and put the following feature description in it.  Note that this cucumber test is assuming you have imported the Hydra sample/fixture objects. To import sample/fixture objects follow the "Import some Sample Content" instructions in "Out of the Box Tour":https://github.com/projecthydra/hydra-head/wiki/Out-of-the-Box-Tour.
+
+<pre>
+  Feature: Homepage Facets
+  I want the home page to include the facets I chose
+
+  Scenario: home page facets
+    When I am on the home page
+    Then I should see "Fedora Model"
+    And I should see "info:fedora/afmodel:ModsAsset"
+    Then I should see "Topic"
+    Then I should see "Journal"
+    And I should see "The Journal of Mock Object"
+    And I should see "Pediatric Nursing"
+    Then I should see "Conference"
+    And I should see "some conference Host"
+</pre>
+
+h4. (2) Run the test - it should fail
+
+Now run the test and watch it fail
+
+<pre>
+  cucumber features
+</pre> 
+
+h4. (3) Change the code
+
+Modify app/controllers/catalog_controller.rb to use the facets you want.
+
+find the section that begins "config.add_facet_field" (around line 42) and replace it with this:
+
+<pre>
+    config.add_facet_field 'has_model_s', :label => 'Fedora Model' 
+    config.add_facet_field 'subject_topic_facet', :label => 'Topic', :limit => 20 
+    config.add_facet_field 'journal_title_info_main_title_facet', :label => 'Journal', :limit => true 
+    config.add_facet_field 'conference_facet', :label => 'Conference', :limit=>true 
+</pre>
+
+h4. (4) Run the test - it should now pass
+
+Now run the test and watch it pass!
+
+<pre>
+  cucumber features
+</pre>
+
+To see the changes for yourself, restart the application.
+
+