hydra-head 4.0.0.rc5 → 4.0.0.rc6

data/DEVELOP_PLUGIN.textile

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

@@ -1,106 +0,0 @@
-h1. Using a checkout from git as your hydra-head or active-fedora gem:
-
-h2. Advanced usage: Running against the freshest version of the hydra-head code from Github
-
-*We don't recommend this for new users or for production applications*, but it is very useful during active development.
-
-If you are in a position where you want/need to run your application with the very latest hydra-head code from Github, this is easy to do.  Simply update the line in your Gemfile that lists hydra-head as a dependency and enter this instead:
-
-<pre>
-  gem "hydra-head", :git => "git://github.com/projecthydra/hydra-head.git"
-</pre> 
-
-After updating the Gemfile, re-run 'bundle install'.
-
-You can also do this with other gems.  For example, if you want to force your app to use the latest active-fedora code from the "HYDRA-721" branch on GitHub, you can put this in your Gemfile:
-
-<pre>
-gem "active-fedora", :git=>'git://github.com/mediashelf/active_fedora.git'
-</pre>
-  
-
-
-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>

data/HOW_TO_DEFINE_A_HYDRA_CONTROLLER.textile

@@ -1,21 +0,0 @@
-h1. Defining a custom Controller that Manipulates Hydra Assets
-
-h2. Depositor/Owner Permissions
-
-Two steps are necessary in order to ensure that your Controller will set the permissions properly on Assets.  If you don't follow these steps, users will be able to create objects but won't be able to edit them.
-
-h3. (1) include AssetsControllerHelper in any Custom Controllers
-
-This will provide {AssetsControllerHelper#apply_depositor_metadata} method within your Controllers.  
-
-<pre>
-  # in your custom Controllers
-  include Hydra::AssetsControllerHelper
-</pre>
-
-h3. (2) call apply_depositor_metadata when you create assets
-
-In your controllers, whenever you create an asset, call apply_depositor_metadata to update the rightsMetadata and apply any other metadata about the depositor.
-
-*Important* You must make sure that your models support apply_depositor_metadata.  See "HOW_TO_DEFINE_A_HYDRA_MODEL":http://hudson.projecthydra.org/job/hydra-head-rails3-plugin/Documentation/file.HOW_TO_DEFINE_A_HYDRA_MODEL.html for more information about doing this in your custom models.
-

data/HOW_TO_DEFINE_A_HYDRA_MODEL.textile

@@ -1,64 +0,0 @@
-h1. Defining a custom Hydra Model 
-
-h2. General Introduction/Tutorial
-
-The "HOW_TO_GET_STARTED":http://hudson.projecthydra.org/job/hydra-head-rails3-plugin/Documentation/file.HOW_TO_GET_STARTED.html 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
-
-# Pick xml schema(s)
-# Create "fixture" XML
-# Define or reuse OM Terminologies & Datastream Classes for your XML
-# Write rspec tests for your Datastream 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
-
-Set up rightsMetadata and Depositor/Owner Permissions 
-# make sure objects have a rightsMetadata datastream
-# include Hydra::ModelMethods in your model
-
-OM Topics:
-
-* namespaces
-* Indexing
-** index_as
-** suppressing fields
-** advanced indexing with custom solr schemas (:displayable and :searchable)
-* retrieving Terms & Values
-
-h2. rightsMetadata and Depositor/Owner Permissions
-
-Two steps are necessary in order to ensure that your controllers will be able to set the 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":http://hudson.projecthydra.org/job/hydra-head-rails3-plugin/Documentation/file.HYDRA_ACCESS_CONTROLS.html
-
-h3. (1) make sure 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. (2) include Hydra::ModelMethods in your model or define custom apply_depositor_metadata method on yoru Model
-
-{Hydra::ModelMethods} will provide {Hydra::ModelMethods#apply_depositor_metadata} method within your Controllers.  
-
-You might want to override that method with model-specific behavior.  The most important behavior to retain is adding +depositor_id+ to the asset's individual edit permissions if the asset has a rightsMetadata datastream.
-
-<pre>
-  # in your model
-  include Hydra::ModelMethods
-</pre>
-
-

data/HYDRA_ACCESS_CONTROLS.textile

@@ -1,27 +0,0 @@
-h1. Understanding Hydra Access Controls
-
-h2. How Permissions are Expressed in Hydra rightsMetadata
-
-h2. How Permissions are Indexed into Solr Documents
-
-h2. How you can use Alternative Field Names in Solr to Enforce Permissions
-
-h3. The Access Controls Evaluation helpers
-
-In your controllers and views you can test whether the current user has read or edit permissions on the current document by calling {reader?} or {editor?}
-
-To test another type of permission, you can use {test_permission?}
-
-h2. Assigning "Public" permissions
-
-In order to give permissions to the public (including users who are not logged in), simply grant group permissions for the "public" group.  For example, to give the public "read" permissions, add this to the rightsMetadata
-
-<pre>
-  <access type="read">
-    <machine>
-      <group>public</group>
-    </machine>
-  </access>
-</pre>
-
-This will add "public" to read_access_t in solr.

data/INITIAL_APP_MODS.textile

@@ -1,223 +0,0 @@
-h1. Initial Modifications to Your Own Hydra Application
-
-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 Write a Simple Spec (an RSpec test)
-# How to Change the Rails Application Name of Your Hydra Application
-# How to Write a Simple Cucumber Feature
-# How to Change the Home Page Text for Your Hydra Application
-# How to Change the Facets displayed for Limiting your Search
-# How to Override a Helper Method
-
-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.
-
-h3. Changing the Home Text (also Demonstrates Writing a Feature)
-
-The home text is set in the view partial (vendor/plugins/hydra-head/)app/views/catalog/_home_text.html.erb
-
-Because it is set in a view, 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"
-      And I should see "Isn't it great?"
-      And I should see "Search"
-</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.)
-
-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.
-
-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 id="results">
-	
-	<%= render :partial=>'search_form' %>
-	
-	<div class="home_text">
-		<h1>Welcome to My Local Hydra App</h1>
-		<br/>
-		<p>This is my local Hydra application.  Isn't it great?
-		</p>
-	</div>
-
-</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.
-
-h3. 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.
-
-<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 blacklight_config.rb to use the facets you want.
-
-In config/initializers/blacklight_config.rb, find the section that begins "config[:facet] =" (around line 45) and replace it with this:
-
-<pre>
-  config[:facet] = {
-    :field_names => (facet_fields = [
-      "has_model_s",
-      "subject_topic_facet",
-      "journal_title_info_main_title_facet",
-      "conference_facet"
-    ]),
-    :labels => {
-      "has_model_s" => "Fedora Model",
-      "subject_topic_facet" => "Topic",
-      "journal_title_info_main_title_facet" => "Journal",
-      "conference_facet" => "Conference"
-    },
-</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.
-
-h3. Overriding a Helper Method (also Demonstrates Writing a Spec)
-
-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" containing this:
-
-<pre>
-  require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
-
-  describe ApplicationHelper do
-    include ApplicationHelper
-  end
-</pre>
-
-A test for checking the application name might be inserted like so:
-
-<pre>
-  require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
-
-  describe ApplicationHelper do
-    include ApplicationHelper
-
-    describe "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.)
-
-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.
-
-