hydra-head 3.0.0pre3 → 3.0.0pre4

data/.gitmodules

@@ -1,6 +1,3 @@
-[submodule "hydra-plugin_test_host"]
-	path = hydra-plugin_test_host
-	url = git://github.com/projecthydra/hydra-plugin_test_host.git 
 [submodule "jetty"]
 	path = jetty
 	url = git://github.com/projecthydra/hydra-jetty.git

data/.rvmrc

@@ -4,6 +4,7 @@
 # development environment upon cd'ing into the directory
 
 ruby_string="ree-1.8.7"
+rubygems_version="1.6.2"
 gemset_name="hyhead-rails3"
 
 # Install rubies when used instead of only displaying a warning and exiting
@@ -25,6 +26,11 @@ else
   rvm --create "$environment_id"
 fi
 
+# Use the specified rubygems_version
+if [[ -n "${rubygems_version}" && ("$(gem --version)" != ${rubygems_version}) ]] ; then
+  rvm rubygems "${rubygems_version}"
+fi
+
 # Ensure that Bundler is installed, install it if it is not.
 if ! (command -v bundle > /dev/null) ; then
 printf "The rubygem 'bundler' is not installed, installing it now.\n"

data/BLACKLIGHT_CONFIG.textile

@@ -0,0 +1,76 @@
+h2. How to Get Facets to Display on Home Page and in Search Results
+
+(note - contribute this to blacklight project and then just link to it in HOW_DO_I doc)
+
+1.  Determine which indexed Solr fields you want to as facets.  
+
+If you have declared them with OM terminology in your datastream models, then they will be the fields in Solr named (something)_facet.
+To see what fields are in Solr, go to:
+
+<pre>
+  http://localhost:8983/solr/development/admin/schema.jsp
+</pre>
+
+where "http://localhost:8983/solr/development" is the base url for your Solr instance.  Click on the "fields" link in the left navigation bar.  You will see a list of all your Solr fields.  Use the "find" function in your web browser to locate all the fields ending with _facet.
+
+Let's say my Solr index has these facet fields:  object_type_facet, set_type_facet, genre_facet
+"tag_facet"
+
+
+2.  Write a test
+
+e.g. features/facets.feature
+
+<pre>
+  Feature: Facets on Home Page and Search Results
+    I want facets to display and work properly
+
+    Scenario: home page facets
+      When I am on the home page
+      Then I should see "Format"
+      And I should see "Book"
+
+    Scenario: search results facets
+      When I am on the home page
+      And I fill in "q" with "dor"
+      And I press "Search"
+      Then I should see "Format"
+      And I should see "Book"
+</pre>  
+
+3.  Ensure test fails
+
+4.  Indicate the facet fields in a Rails initializer.
+
+Facet fields are initially configured by config/initializers/blacklight_config.rb in your Rails app.  You override these configurations by creating a new file in config/initializers  that MUST sort later alphabetically than blacklight_config.  Your hydra_app_config.rb might look something like this:
+
+<pre>
+  # overrides of blacklight_config.rb
+  Blacklight.configure(:shared) do |config|
+  
+    ... 
+
+    # solr fields that will be treated as facets by the blacklight application
+    #   The ordering of the field names is the order of the display
+    config[:facet] = {
+       :field_names => (facet_fields = [
+         "object_type_facet",
+         "set_type_facet",
+         "genre_facet"
+         ]),
+       :labels => {
+         "object_type_facet"=>"Object Type",
+         "set_type_facet"=>"Set Type",
+         "genre_facet"=>"Genre"
+       }   
+    }
+
+    # Have BL send all facet field names to Solr. 
+    config[:default_solr_params] ||= {}
+    config[:default_solr_params][:"facet.field"] = facet_fields
+
+    ...
+</pre>
+
+5.  Ensure test passes.
+

data/CREATE_RAILS_APP.textile

@@ -0,0 +1,323 @@
+h1. Creating a Rails Application with the Hydra-Head Plugin.
+
+This document describes how to create a Hydra rails application.
+
+It does NOT describe how to get the hydra-head plugin code with the pre-configured rails application for testing:  for that, see "DEVELOP_PLUGIN":https://github.com/projecthydra/hydra-head/blob/master/DEVELOP_PLUGIN.textile.
+
+h3. I. Install Prerequisites
+
+See "INSTALL_PREREQ":/projecthydra/hydra-head/blob/master/INSTALL_PREREQ.textile
+
+h2. II. Install a Blacklight Application
+
+This process begins with the installation of the Blacklight ("http://projectblacklight.org":http://projectblacklight.org) rails application.
+
+h4. (1) Create the RVM Gemset and Install Pre-Requisite Gems.
+
+<pre>
+rvm gemset create hydra-head
+rvm use ree-1.8.7@hydra-head
+gem install -v=2.3.11 rails
+gem install sqlite3
+</pre> 
+
+h4. (2) Run the Blacklight Installation Script.
+
+<pre>
+rails ./my-hydra-app -m http://projectblacklight.org/templates/2-8-0.rb 
+</pre>
+
+install gems? yes
+
+run migrations? yes
+
+install solr? no
+
+h4. (3) Put Your New Hydra Rails Application into Version Control.
+
+Set up git repository:
+
+<pre>
+cd my-hydra-app
+git init .
+</pre>
+
+Create a .gitignore file.  A good model is at  "https://github.com/projecthydra/hydra-head/blob/master/.gitignore":https://github.com/projecthydra/hydra-head/blob/master/.gitignore
+
+Do the initial commit:
+
+<pre>
+git add .
+git commit -m "installed blacklight via its template installer"
+</pre>
+
+h4. (4) Add Blacklight Plugin Files into Version Control.
+
+The blacklight template installer has the blacklight plugin code included as a git submodule.  We want it to be added in its entirety into your local git repository.
+
+<pre>
+cp -R vendor/plugins/blacklight/ vendor/plugins/blacklight-temp/
+
+rm -rf vendor/plugins/blacklight  
+git rm vendor/plugins/blacklight
+
+mv vendor/plugins/blacklight-temp vendor/plugins/blacklight
+git add vendor/plugins/blacklight
+git commit -m "blacklight plugin files added to git repository (no longer a submodule)"
+</pre>
+
+h2. III. Add the Hydra-Head Configuration Files to Your Application
+
+Note: these steps will eventually be handled by a generator.  For now:
+
+h4. (1) Clone a copy of the hydra-head repository
+
+Make sure you don't do this within the rails application you are creating.
+
+<pre>
+cd ..
+git clone git://github.com/projecthydra/hydra-head.git
+cd my-hydra-app
+</pre>
+
+h4. (2) Copy the desired hydra-head config files
+
+Be careful not to override routes.rb!  The following commands avoid this:
+
+<pre>
+cp config/routes.rb routes-copy.rb
+cp ../hydra-head/Gemfile ./
+cp -R ../hydra-head/config/* config/
+mv routes-copy.rb config/routes.rb 
+</pre>
+
+Copy the fedora and solr config files into the application. This is where you will keep your application-specific copies of solr and fedora configuration. When running the app, you need to copy these files into your copies of Fedora and Solr. When you're using the copy of hydra-jetty in the"jetty" directory, running rake hydra:jetty:load will copy them into the jetty directory for you.
+
+<pre>
+cp -R ../hydra-head/solr ./
+cp -R ../hydra-head/fedora ./
+</pre>
+
+
+When you run @git status@ you should see something like this: 
+
+<pre>
+#	modified:   config/initializers/blacklight_config.rb
+#	modified:   config/initializers/mime_types_.rb
+#	modified:   config/solr.yml
+
+# Untracked files:
+#	         Gemfile
+#	         config/fedora.yml
+#	         config/initializers/fedora_config.rb
+#	         config/initializers/hydra_config.rb
+#	         config/role_map_cucumber.yml
+#	         config/role_map_development.yml
+#	         config/role_map_production.yml
+#	         config/role_map_test.yml
+#	         config/solr_mappings.yml
+</pre>
+
+h4. (3) Put the hydra-head database migrations into the root app.
+
+<pre>
+cp ../hydra-head/db/migrate/* db/migrate
+</pre>
+
+h4. (4) Add .rvmrc
+
+Only do this if you're using RVM.  DON'T do this if you're going to use this application for running tests.  (Naomi asks "Why?")
+
+<pre>
+cp ../hydra-head/.rvmrc .	
+</pre>
+
+h4. (5) Commit the files to your git repository:
+
+<pre>
+git add *
+git commit -a -m "adding hydra-head configuration files, including db migrations and .rvmrc"
+</pre>
+
+h2. IV. Get Required Gems
+
+Now that you have the hydra-head Gemfile in your application, you can run bundle install to get the required gems:
+
+<pre>
+bundle install 
+</pre>
+
+h2. V. Install Required Plugins
+
+h3. (1) engines plugin
+
+Move Blacklight's copy of the engines plugin into the app's vendor/plugins directory.  This is mainly so you have access to the rake tasks that the engines plugin provides.
+
+<pre>
+  mv vendor/plugins/blacklight/vendor/plugins/engines vendor/plugins/
+</pre>
+
+h3. (2) hydra-head plugin
+
+There are many ways to get the hydra-head code into vendor/plugins.  One way is to use script/plugin install:
+
+<pre>
+script/plugin install git://github.com/projecthydra/hydra-head.git 
+</pre>
+
+h3. (3) white_list plugin
+
+This is a legacy dependency.  We will be removing it soon, but for now you need to have it installed in order for hydra-head to run properly.
+
+<pre>
+script/plugin install git://github.com/projecthydra/white_list.git
+</pre>
+
+h3. (4) fluid-infusion plugin
+
+This is another legacy dependency.  Now we mainly rely on it just for the implementation of swfuploader.
+
+<pre>
+script/plugin install  git://github.com/mediashelf/fluid-infusion.git
+</pre>
+
+h3. (5) blacklight plugin: patch CatalogController
+
+Note: (this may no longer be necessary 2011-06-14)
+
+(or maybe: the long-term fix to this will be to implement before_render callbacks in CatalogController.show and refactor hydra-head to use those callbacks instead of aliasing the show method itself.)
+
+Blacklight's CatalogController.show method breaks the hydra-head overrides.  To fix this, comment out lines 47-51 in vendor/plugins/blacklight/app/controllers/catalog-controller.rb:
+
+<pre>
+  # Add all dynamically added (such as by document extensions)
+  # export formats.
+  #@document.export_formats.each_key do | format_name |
+  #  # It's important that the argument to send be a symbol;
+  #  # if it's a string, it makes Rails unhappy for unclear reasons.
+  #  format.send(format_name.to_sym) { render :text => @document.export_as(format_name) }
+  #end
+</pre>
+
+h3. (6) Add the plugins to git.
+
+<pre>
+git add *
+git commit -a -m "adding required plugins"
+</pre>
+
+h2. VI. Update config/environment.rb to Load Plugins in the Correct Order
+
+h4. (1) Edit config/environment.rb.
+
+In config/environment.rb, change line 8 to use '../vendor/plugins/engines/boot' instead of '../vendor/plugins/blacklight/vendor/plugins/engines/boot'
+
+<pre>
+  require File.join(File.dirname(__FILE__), '../vendor/plugins/engines/boot')
+  # require File.join(File.dirname(__FILE__), '../vendor/plugins/blacklight/vendor/plugins/engines/boot')
+</pre>
+
+In that same file, add the following lines inside the @Rails::Initializer.run do |config|@ code block. This will set the load order for plugins, ensuring that blacklight is loaded before hydra-head.
+
+<pre>
+config.plugins = %W(engines blacklight fluid-infusion hydra-head white_list)
+</pre>
+
+h4. (2) Commit the changes to git.
+
+<pre>
+git commit config/ -m "Update config/environment.rb to load plugins in the right order"
+</pre>
+
+h2. VII. Update Application's application_controller and application_helper to Use Hydra-Head Plugin
+
+h4. (1) Edit app/controllers/application_controller.rb
+
+Change the first line to require the hydra-head plugin's controller rather than blacklight's:
+
+<pre>
+require_dependency( 'vendor/plugins/blacklight/app/controllers/application_controller.rb')
+</pre>
+
+becomes
+
+<pre>
+require_dependency( 'vendor/plugins/hydra-head/app/controllers/application_controller.rb')
+</pre>
+
+h4. (2) Edit app/helpers/application_helper.rb
+
+Change the first line to require the hydra-head plugin's helper rather than blacklight's:
+
+<pre>
+require 'vendor/plugins/blacklight/app/helpers/application_helper.rb'
+</pre>
+
+becomes
+
+<pre>
+require 'vendor/plugins/hydra-head/app/helpers/application_helper.rb'
+</pre>
+
+h4. (3) Commit the changes to git.
+
+<pre>
+git commit app/ -m "Update application_controller and application_helper to require hydra-head plugin, not blacklight"
+</pre>
+
+
+h2. VIII. If You Plan to Use This Rails App For Running the Automated Tests
+
+Stop here and go to "DEVELOP_PLUGIN":https://github.com/projecthydra/hydra-head/blob/master/DEVELOP_PLUGIN.textile.
+
+h2. IX. Run the Database Migrations
+
+The following will run the migrations for the app and for its plugins:
+
+<pre>
+rake db:migrate:all
+</pre>
+
+h2. X. Spin up Solr and Fedora
+
+The easiest way is to put a copy of hydra-jetty into the jetty directory within your app. This provides copies of solr and fedora that you can use for testing and development purposes.
+
+h4. (1) Get hydra-jetty (jetty preconfigured with Fedora and Solr)
+
+<pre>
+git submodule add git://github.com/projecthydra/hydra-jetty.git jetty
+</pre>
+
+h4. (2) Add submodule SHA to git, but not the hydra-jetty files.
+
+<pre>
+(add line containing "jetty" to .git/info/excludes file)
+git add .gitmodules
+git commit -m "Adding hydra-jetty submodule"
+</pre>
+
+h4. (3) Run Jetty
+
+_Stop any copies of jetty (or anything else using port 8983) before running this command._
+(Note that java 1.6 must be invoked by the "java" command or Fedora won't work.)
+
+The following will copy Solr and Fedora configuration files over to jetty in addition to starting it:
+
+<pre>
+rake hydra:jetty:load
+</pre>
+
+h2. XI. Run Your New Hydra Application
+
+<pre>
+  script/server
+</pre>
+
+You should now be able to go to your application at http://localhost:3000.
+
+Note that there are no objects pre-installed into Fedora (or Solr).
+
+h2. XII. Develop your Hydra Application with ActiveFedora and OM
+
+See "HOW_TO_GET_STARTED":https://github.com/mediashelf/om/blob/master/HOW_TO_GET_STARTED.textile.
+

data/DEVELOP_PLUGIN.textile

@@ -0,0 +1,90 @@
+h1. Setting Up the Hydra-Head Plugin as a Project Containing a Rails Application for Testing or Demo
+
+This document describes how to set up a project for the hydra-head plugin code itself - primarily intended for the hydra-head plugin developers.  It will contain a pre-configured rails application for testing the hydra-head plugin.
+
+It does NOT describe how to set up a rails application that uses the hydra-head plugin.  For that, see "CREATE_RAILS_APP":https://github.com/projecthydra/hydra-head/blob/master/CREATE_RAILS_APP.textile.
+
+h2. Install the Hydra-Plugin and its Contained Test Host Application
+
+h4. (0) Install Prerequisites.
+
+See "INSTALL_PREREQ":/projecthydra/hydra-head/blob/master/INSTALL_PREREQ.textile
+
+h4. (1) Get the hydra-head engines plugin from github and include the testing rails application.
+
+<pre>
+git clone --recursive git@github.com:projecthydra/hydra-head.git
+cd hydra-head
+</pre>
+
+This will also initialize and update the jetty and hydra-plugin_test_host git submodules. The former is a copy of Jetty pre-configured for Hydra with Fedora and Solr installed. The latter is a preconfigured Rails application to house and test the hydra-head engines plugin.
+
+This <b>hydra-head directory</b> is the <b><i>root of the plugin</i>.</b>
+
+h4. (2) Use bundler to install the gem dependencies.
+
+<pre>
+  bundle install
+</pre>
+
+Note that if you have RVM installed, it will create/use a gemset called "hyhead".
+
+
+h4. (3) Put a copy of the hydra-head plugin into the testing application
+
+The rails application used for testing MUST have a copy of the hydra-head plugin added to its vendor/plugins directory. We provide a "rake task":http://hudson.projecthydra.org/job/hydra-head-rails2-plugin/Documentation/file.README_RAKE_TASKS.html#hyhead_Test_Host_Setup__setup_test_host for this which copies your current hydra-head plugin code into hydra-plugin_test_host/vendor/plugins as well as the fixtures and cucumber features required for testing.
+
+<pre>
+rake hyhead:setup_test_host
+</pre>
+
+h4. (5) Migrate the test databases
+
+See below to reset the test databases when re-running tests.
+
+You must do this within the <b><i>hydra-plugin_test_host</i> directory</b>, not at the root of the plugin.
+
+<pre>
+  cd hydra-plugin_test_host
+</pre>  
+
+To ensure that the tests do not rely on non-test data, do this:
+
+<pre>
+  rake db:drop:all 
+</pre>
+
+Migrate the test databases:
+
+<pre>
+  rake db:migrate RAILS_ENV=test  
+</pre>
+
+In case you ever run the server in development mode, you will need to migrate the databases without RAILS_ENV set to test:
+
+<pre>
+  rake db:migrate
+</pre>
+
+Now cd back up to the root of the <b><i>hydra-head plugin</i> directory</b>:
+
+<pre>
+  cd ../
+</pre>
+
+h3. Now you're ready to run the tests
+
+If you want to run the tests, see "TESTING_PLUGIN":/projecthydra/hydra-head/blob/master/TESTING_PLUGIN.textile
+
+h2. Running the Testing Application
+
+The test host app is a regular Rails app with Blacklight installed.  It's configured with the assumption that the hydra-head plugin is installed into vendor/plugins/hydra-head.
+
+Hydra expects Fedora and Solr instances to be running (for testing, a jetty instance is provided in the hydra-head plugin directory.  See also config/solr.yml and config/fedora.yml).
+
+Change into the root of the test app and start it like you normally start any rails app.
+
+<pre>
+cd hydra-plugin_test_host
+script/server
+</pre>

data/GIT_WORKFLOW.textile

@@ -0,0 +1,84 @@
+h1. Git Workflow (with command line examples) for working on Hydra Projects
+
+h2. Reference Material/Reading:
+
+Good places to read about git workflows:
+
+* "Diaspora Git Workflow":https://github.com/diaspora/diaspora/wiki/Git-Workflow
+* "Thinkup Developer Documentation":http://thinkupapp.com/docs/contribute/developers/devfromsource.html
+
+You might want to set up your shell prompt to tell you which git branch you're in.
+
+* "Displaying git branch info in your bash prompt":http://yourmediashelf.com/2011/08/displaying-git-branch-info-in-bash-prompt/
+
+h2. Creating a Feature Branch then Rebasing, Merging and Cleaning Up
+
+*Scenario:* You're working on the HYDRA-333 ticket.  
+
+# You already have a working copy of hydra-head cloned to your local machine.
+# Your work is starting from the contents of hydra-head/master
+
+The steps:
+
+# Create a feature branch
+# If necessary, push a copy of the working branch to github
+# Rebase the feature branch
+# Merge the finished work into Master
+# Clean up after yourself
+
+Here's how to do the right thing with git on the command line.  *Note*: the parts in parentheses indicates which branch you should be on when you run the command.  If it doesn't matter which branch you're on, this is indicated with (*).
+
+h3. Create your feature branch
+
+<pre>
+cd hydra-head
+(master) git checkout -b HYDRA-333
+</pre>
+
+Make changes and commit them to your feature branch like normal.
+
+<pre>
+(HYDRA-333) git add …
+(HYDRA-333) git commit …
+</pre>
+
+h3. If necessary, push a copy of the feature branch to github
+
+If you need to share your feature branch, push it to github
+
+<pre>
+(HYDRA-333) git push origin HYDRA-333
+</pre>
+
+h3. Rebase the feature branch
+
+Repeat work until the HYDRA-333 ticket is ready to close, then rebase that work & merge it into the master branch ...
+
+<pre>
+(*) git checkout master
+(master) git pull origin master
+(master) git checkout HYDRA-333 
+(HYDRA-333) git rebase master
+... walk through the rebase ...
+</pre>
+
+At this point, you should *rerun your full test suite* to make sure that the rebase did not break anything.  
+
+h3. Merge the finished work into Master
+
+If all of the tests pass after the rebase, you're ready to merge your work into master and push it to github.
+
+<pre>
+(HYDRA-333) git checkout master
+(master) git merge HYDRA-333
+(master) git push origin master
+</pre>
+
+h3. Clean up after yourself
+
+Now delete the local & remote copies of the feature branch 
+
+<pre>
+(master) git branch -d HYDRA-333
+(master) git push origin :HYDRA-333
+</pre>