hydra-head 3.0.0pre1 → 3.0.0pre2

data/HYDRA_ACCESS_CONTROLS.textile

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

@@ -0,0 +1,239 @@
+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.
+
+h3. 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
+
+
+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.  tests tests tests
+
+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.
+
+(when should it be a 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. Run generator for specs
+
+To create the infrastructure pieces to write specs:
+
+<pre>
+  ./script/generate rspec
+</pre>
+
+h4. Run generator for features
+
+To create the infrastructure pieces to write cucumber features:
+
+<pre>
+  ./script/generate cucumber
+</pre>
+
+
+h3. Easy Changes for Practice.
+
+h3. Changing the Facets
+
+h4. 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>
+
+Now run the test and watch it fail
+
+<pre>
+  cucumber features
+</pre> 
+
+h4. 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>
+
+Now run the test and watch it pass!
+
+<pre>
+  cucumber features
+</pre>
+
+To see the changes for yourself, restart the application.
+
+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. 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.
+
+

data/README.textile

@@ -50,15 +50,15 @@ First, add them to the Gemfile of your application:
 <pre>
   source 'http://rubygems.org'
 
-  gem 'rails', '>=3.0.4'
+  gem 'rails', '~>3.0.4'
 
   gem 'blacklight', '~> 3.0.0'
   gem 'hydra-head', '3.0.0pre1'
-  
+
   # We will assume that you're using sqlite3 for testing/demo, 
   # but in a production setup you probably want to use a real sql database like mysql or postgres
   gem 'sqlite3-ruby', :require => 'sqlite3'
-  
+
   #  We will assume you're using devise in tutorials/documentation. 
   # You are free to implement your own User/Authentication solution in its place.
   gem 'devise'
@@ -76,7 +76,6 @@ First, add them to the Gemfile of your application:
          gem 'capybara'
          #gem 'webrat'
          #gem 'aruba'
-         gem 'factory_girl'
          gem 'bcrypt-ruby'
   end
 </pre>
@@ -87,15 +86,24 @@ To install all of the dependencies, run:
 bundle install
 </pre>
 
+This will take a _very_ long time the first time you run it.  IF you become impatient, hit Ctl+C then enter this:
+
+<pre>
+  gem install blacklight
+  gem install hydra-head -v 3.0.0pre1
+</pre>
+
+Then re-run bundle install and it will run slightly faster.
+
 h3. Run the generators and migrations:
 
 Run the blacklight generator
 
-<pre>rails g blackight -devise</pre>
+<pre>rails g blacklight -devise</pre>
 
 Run the hydra-head generator
 
-<pre>rails g hydra-head -df</pre>
+<pre>rails g hydra:head -df</pre>
 
 Run the database migrations
 
@@ -122,8 +130,15 @@ The Hydra project provides a copy of Jetty with Fedora and Solr pre-installed.
 Most projects add hydra jetty to their code as a git submodule
 
 <pre>
-  git submodule add git@github.com:projecthydra/hydra-jetty.git jetty
+  git submodule add git://github.com/projecthydra/hydra-jetty.git jetty
   git commit -m"added jetty submodule"
+  cd jetty
+  git fetch --tags
+  git checkout last_solr_multicore
+  git checkout -b last_solr_multicore
+  cd ..
+  git add jetty
+  git commit -m "Pinned jetty to last_solr_multicore"
 </pre>
 
 Now that you've added the submodule to your git repository, whenever you grab a new working copy of the code, you can get hydra-jetty by running:

data/README_RAILS3_CHANGES.textile

@@ -3,9 +3,15 @@ h2. Fixtures
 
 Fixtures are loaded from a directory _within the test app_, which is updated when you run rake hyhead:setup_test_app so in order to update a fixture, you must change it in test_support/fixtures and then either re-run rake hyhead:setup_test_app or copy the fixture into tmp/test_app/test_support/fixtures
 
+h2. Cucumber tests
+
+We have switched from Webrat to Capybara as the driver for our Cucumber tests.  If you have been writing your own cucumber tests (you should!) and want to stay in sync with the rest of the hydra developers, you should switch to Capybara and pull all of the "step definitions from the hydra code":https://github.com/projecthydra/hydra-head/tree/rails3/test_support/features/step_definitions into your local app.
+
+Sometime soon, we hope to wrap our step definitions into the Hydra code itself so that you can use them without having to manually copy the files into your step_definitions directory.  This will probably be done in a way that imitates the "Factory Girl step definitions":http://robots.thoughtbot.com/post/284805810/gimme-three-steps
+
 h2. User objects
 
-Blacklight has switched to using devise instead of authlogic as its default user/authentication system.  As part of this switch, no longer have a "login" attribute as their unique identifier.  Instead, you must use email as the unique identifier.  
+Blacklight has switched to using devise instead of authlogic as its default user/authentication system.  As part of this switch, no longer have a "login" attribute as their unique identifier.  Instead, you must use email as the unique identifier.  We have added a "login" method that 
 
 h2. User Attributes
 
@@ -32,11 +38,26 @@ Change your features and role_map YAML files accordingly.
 
 h2. How to upgrade
 
+The sureest and easiest path to upgrading a hydra head application from Rails 2 to Rails 3, is to start a new project from scratch.
+
 * Create a new rails 3 project
 * Add ```gem 'blacklight'``` and ```gem 'hydra-head'``` to the Gemfile
 * run ```bundle install```
 * cp -r old_project/vendor/plugin/old_project_plugin/app/* new_project/app
 * cp -r old_project/vendor/plugin/old_project_plugin/lib/* new_project/lib
+<<<<<<< HEAD
+* copy any tests (test, spec, feature, etc) from the old_project_plugin directory to the new project
+* Run the generators 
+```rails g blackight -devise```
+Run the hydra-head generator
+```rails g hydra:head -df```
+Run the database migrations
+```rake db:migrate
+rake db:migrate RAILS_ENV=test```
+
+* If you will be writing cucumber tests, run the cucumber generator
+```rails g cucumber:install```
 * copy any tests (test, spec, feature, etc) from the old_project_plugin directory to the new project 
- 
+* update your solrconfig.xml
+* update your role_map_...yml files to use appropriate identifiers
 

data/app/views/catalog/_sort_and_per_page.html.erb

@@ -1,8 +1,9 @@
 <div id="sortAndPerPage">
 	<% unless @response.response['numFound'] < 2 %>
   	<%= form_tag catalog_index_path, :method=>:get, :class=>'per_page' do %>
-  		<%= label_tag(:per_page, "Show " + select_tag(:per_page, options_for_select(['10', '20', '50', '100'], h(params[:per_page])), :title => "Number of results to display per page", :onchange => 'this.form.submit()') + " per page") %>
-
+  		<%= label_tag(:per_page, "Show") %>
+  		<%= select_tag(:per_page, options_for_select(['10', '20', '50', '100'], h(params[:per_page])), :title => "Number of results to display per page", :onchange => 'this.form.submit()') %>
+      per page
       <%= search_as_hidden_fields(:omit_keys => [:page, :per_page]) %>
 		
       <noscript><%= submit_tag 'update' %></noscript>

data/app/views/catalog/show.html.erb

@@ -26,7 +26,7 @@
 <% end -%>
 <div id="document" class="<%= controller.action_name == "edit" ? "document_edit" : "document_show" %>">
   <div id="<%= format_pid(@document[:id]) %>">
-    <h1><%= render_document_heading.html_safe %></h1>
+    <%= render_document_heading.html_safe %>
     <div class="document">
       <%= render_document_partial @document, params["action"] %>
     </div>

data/lib/generators/hydra/cucumber_support_generator.rb

@@ -0,0 +1,29 @@
+# -*- encoding : utf-8 -*-
+require 'rails/generators'
+require 'rails/generators/migration'     
+
+module Hydra
+class CucumberSupportGenerator < Rails::Generators::Base
+  
+  source_root File.expand_path('../../../../test_support/features', __FILE__)
+  
+  argument :features_dir, :type => :string , :default => "features"
+        
+  desc """
+  This Generator copies Hydra's cucumber step definitions and paths into your application's features directory.
+  We have plans to provide the step definitions directly through the hydra-head gem without requiring this step of copying the files.
+  In the meantime, you need to copy the files in order to use them. 
+  
+  Defaults to assuming that your cucumber features live in a directory called \"features\".  To pass in an alternative path to your features directory,
+  
+  rails generate hydra:cucumber_support test_support/features
+  
+  """
+  
+  def copy_cucumber_support
+    directory("step_definitions", "#{features_dir}/step_definitions")
+    copy_file("support/paths.rb", "#{features_dir}/support/paths.rb")
+  end
+  
+end
+end

data/lib/generators/hydra/head_generator.rb

@@ -2,8 +2,6 @@
 require 'rails/generators'
 require 'rails/generators/migration'     
 
-# require "generators/blacklight/blacklight_generator"
-
 module Hydra
 class HeadGenerator < Rails::Generators::Base
   include Rails::Generators::Migration
@@ -14,7 +12,7 @@ class HeadGenerator < Rails::Generators::Base
   
     desc """
   This generator makes the following changes to your application:
-    1. Creates several database migrations if they do not exist in /db/migrate
+    1. Creates a database migration for superusers if they do not exist in /db/migrate
     2. Adds additional mime types to you application in the file '/config/initializers/mime_types.rb'   
     3. Creates config/initializers/hydra_config.rb 
     4. Creates config/initializers/fedora_config.rb 
@@ -77,16 +75,12 @@ EOF
   # Implement the required interface for Rails::Generators::Migration.
   # taken from http://github.com/rails/rails/blob/master/activerecord/lib/generators/active_record.rb
   def self.next_migration_number(dirname)
-    unless @previous_migration_nr
-      if ActiveRecord::Base.timestamped_migrations
-        @previous_migration_nr = Time.now.utc.strftime("%Y%m%d%H%M%S").to_i
-      else
-        @previous_migration_nr = "%.3d" % (current_migration_number(dirname) + 1).to_i
-      end
+    unless @prev_migration_nr
+      @prev_migration_nr = Time.now.utc.strftime("%Y%m%d%H%M%S").to_i
     else
-      @previous_migration_nr +=1 
+      @prev_migration_nr += 1
     end
-    @previous_migration_nr.to_s
+    @prev_migration_nr.to_s
   end
 
   # Add Hydra behaviors to the user model
@@ -98,7 +92,7 @@ EOF
         "\n include Hydra::User\n"        
       end
     else
-      puts "     \e[31mFailure\e[0m  Hydra requires a user object in order to apply access controls. This generators assumes that the model is defined in the file /app/models/user.rb, which does not exist.  If you used a different name, please re-run the migration and provide that name as an argument. Such as \b  rails -g hydra:head client" 
+      puts "     \e[31mFailure\e[0m  Hydra requires a user object in order to apply access controls. This generators assumes that the model is defined in the file /app/models/user.rb, which does not exist.  If you used a different name, please re-run the generator and provide that name as an argument. Such as \b  rails -g hydra:head client" 
     end    
   end
   
@@ -139,8 +133,6 @@ EOF
   end
   
   def create_migration_file
-    migration_template 'migrations/add_user_attributes_table.rb', 'db/migrate/add_user_attributes_table.rb'
-    sleep 1 # ensure scripts have different time stamps
     migration_template 'migrations/create_superusers.rb', 'db/migrate/create_superusers.rb'    
   end