hydra 6.2.0.rc1 → 6.2.0

data/doc/Dive-into-Hydra.md

@@ -0,0 +1,62 @@
+This tutorial is known to work with [hydra](http://rubygems.org/gems/hydra) release version 6.1.0.   
+_Please update this wiki to reflect any other versions that have been tested._
+
+# Prerequisites
+
+This tutorial assumes that you have some basic familiarity with Ruby and Rails.  If you are new to Rails, we recommend going through the [RailsBridge Tutorial](http://curriculum.railsbridge.org/intro-to-rails/) first.
+
+A fun way to learn about the basic Rails syntax and patterns is the [Rails for Zombies](http://railsforzombies.org/) tutorial.
+
+The tutorial also mentions using [Ruby Version Manager](http://rvm.io), a.k.a RVM.  Before starting this tutorial, visit the [RVM website](http://rvm.io/) to learn about how that tool is used.  RVM is not required in order to do the tutorial, but you will probably find it useful.
+
+# System Requirements
+Your system should have the following installed before beginning the walkthrough
++ [ruby](http://www.ruby-lang.org/en/) 1.9.3 or 2.0.0
++ [rails](http://rubyonrails.org/)  ~>3.2.13 or ~>4.0.0
++ [git](http://git-scm.com/)
++ [java](http://www.java.com/en/) runtime >= 6.0 
+
+# Goals
+* Create a Hydra Head
+* Run Fedora and Solr underneath the Hydra Head
+* Start & Stop the Application
+* Start & Stop Fedora and Solr
+* Define Models for Content to put into your Hydra Head (in this case Books and Pages)
+* Use your Models to Create objects in Fedora and Solr
+* See where content is persisted in Fedora and indexed in Solr
+* Modify how metadata is indexed in Solr
+* Use Git to Track Code Changes
+
+# Steps/Lessons
+1. [[Lesson: Generate a Rails Application]]
+1. [[Lesson: Create a git Repository]]
+1. [[Lesson: Add the Hydra Dependencies]]
+1. [[Lesson: Run the Hydra generator]]
+1. [[Lesson: Install hydra-jetty]]
+1. [[Lesson: Start Jetty]]
+1. [[Lesson: Start the Application & Search for Results]]
+1. [[Lesson: Build a Book Model]]
+1. [[Lesson: Turn Off Access Controls]]
+1. [[Lesson: Make Blacklight Return Search Results]]
+
+## Bonus
+You've completed the main tutorial, the following lessons can be completed in any order based on your interests:  
+
+1. [[Lesson: Define Relationships Between Objects]]  
+1. [[Lesson: Adding Content Datastreams]]  
+1. [[Lesson: Generate Rails Scaffolding for Creating and Editing Books]]  
+1. [[Lesson: Set up your Rails Application to use RSpec]]  
+
+# Next Steps
+You've finished the initial Hydra tutorial and learned about setting up the basic hydra framework, building basic data models, establishing relationships between models, and modifying the basic user interface provided in a default hydra install.  There is still lots more to learn.  At this point, you can explore the ideas in this tutorial further by spending some time building out your models to support more complex metadata, further customizing your application views, and/or adding tests to make your applications more robust and easy to maintain.
+
+There's lots more Hydra though, so you may wan to check out the following tutorials
+- [Tame Your XML With OM](https://github.com/projecthydra/om/wiki/Tame-your-XML-with-OM) shows you how to configure Hydra to parse metadata from source XML documents
+- [Access Controls with Hydra](https://github.com/projecthydra/hydra-head/wiki/Access-Controls-with-Hydra) teaches you to configure roles and access rights that determine which content can be viewed by various user roles assigned to users of your repository
+- Even though the information there is not specific to Hydra, [Getting Started with Rails](http://guides.rubyonrails.org/getting_started.html) is a great place to learn more about Model, View, and Controller conventions within Rails that can be applied to building your own Hydra-based repository.
+
+You should also say hello on the [hydra-tech mailing list](https://groups.google.com/forum/?fromgroups#!forum/hydra-tech) and let us know what you're using Hydra for.  
+  
+Check out the Hydra Project Website at [http://projecthydra.org](http://projecthydra.org)  
+
+![Project Hydra Logo](https://github.com/uvalib/libra-oa/blob/a6564a9e5c13b7873dc883367f5e307bf715d6cf/public/images/powered_by_hydra.png?raw=true)

data/doc/Filtering-search-results-with-hydra-access-controls.md

@@ -0,0 +1,16 @@
+In you catalog_controller.rb add the following lines:
+
+```
+include Hydra::Controller::ControllerBehavior
+before_filter :enforce_show_permissions, :only=>:show
+CatalogController.solr_search_params_logic += [:add_access_controls_to_solr_params]
+```
+
+Additionally, if you want to remove FileAssets from search results you can add:
+```
+CatalogController.solr_search_params_logic += [:exclude_unwanted_models]
+```
+
+Running the generator: `rails g hydra:head`  typically takes care of this for you.
+
+

data/doc/For-Developers.md

@@ -0,0 +1,47 @@
+## Community Principles
+Hydra Community Principles
+
+## Getting Connected
+Mailing lists, committers calls, etc. are all listed on the [Connect](https://wiki.duraspace.org/display/hydra/Connect) page of the [The Hydra Project wiki](https://wiki.duraspace.org/display/hydra/The+Hydra+Project).
+
+## Getting Code
+All of our code is hosted on Github in the [projecthydra](https://github.com/projecthydra) account.
+
+## On-line Resources and Tutorials
+### For New and Potential Adopters:
+* New adopters and potential adopters may find the pages here useful: http://projecthydra.org/
+* See Hydra Heads (Known Implementations) for more information about each of the Hydra Heads.
+* Developers may find the [Hydra-Head Walkthrough](https://github.com/projecthydra/hydra-head/wiki/Code4lib-walkthrough) useful.
+
+### For Architecture Level:
+* See the Duraspace projecthydra wikis for information at the architecture level: http://wiki.duraspace.org/display/hydra/
+
+### For Developers:
+* Code is hosted on Github: https://github.com/projecthydra
+* Each of the gems in the hydra framework has its own wiki associated its individual code repository
+* [Contributing code](https://github.com/projecthydra/hydra/blob/master/CONTRIBUTING.md) 
+* API documentation (class and method level documentation) is currently published for each build on the Hydra Continuous Integration Server.
+* Some particular documents of interest (these may migrate to the github wikis for these github repositories)
+    * A Hydra Head interactive tutoral lives [here](https://github.com/projecthydra/hydra-head/wiki/Code4lib-walkthrough)
+    * [How to Get Started building your Hydra Head](https://github.com/projecthydra/hydra-head/wiki/How-to-Get-Started)
+    * [Steps to Defining a new Model for your Hydra Applications](https://wiki.duraspace.org/display/hydra/Steps+to+Defining+a+new+Model+for+your+Hydra+Applications)
+    * [ActiveFedora Console Tour] (https://github.com/projecthydra/active_fedora/wiki/Getting-Started:-Console-Tour)
+    * [OM documentation](https://github.com/projecthydra/om/blob/master/README.textile)
+    * Recommended Code Commenting Practices: think about using [YARD](http://rubydoc.info/docs/yard/file/docs/GettingStarted.md), at least provide comments that can illuminate [RDoc](http://rdoc.rubyforge.org) generated documentation
+    * Hydra's Bundled Jetty https://github.com/projecthydra/hydra-jetty
+    * [OM Terminologies in the Wild](https://wiki.duraspace.org/display/hydra/OM+Terminologies+in+the+Wild)
+
+## What Developer Skills are Needed?
+The curriculum for Data Curation Experts's annual HydraCamp reflects the skills that a Hydra development team should ideally have. They should be able to:
+* build a Rails3 Application with RSpec & Capybara tests and track it in Git
+* work with MVC, Rails Plugins, Git workflow, and be able to write good tickets
+* model & create Fedora objects with XML & RDF metadata then index them in Solr
+* use Blacklight to build a customized Solr-driven search/discovery interface
+* build a user interface for creating and editing Fedora objects
+## Where Can Developers Get Training?
+The community offers multi-day public HydraCamps at least once a year in North America. Additional single and half-day workshops are frequently offered in conjunction with other major Library and Library Technology Conferences. HydraCamps are typically facilitated by Data Curation Experts who can also be engaged for private HydraCamp events or custom training engagements. Contact Information is available at http://curationexperts.com
+
+## Tickets: Reporting Bugs & Requesting Features
+We use Github, issues as our project tracker. Please report issues against the git repository for the specific gem you are having issues with. If you are unable to identify the gem in which your problem is occurring, please e-mail the hydra-tech@googlegroups.com mailing list to help narrow your issue.
+
+For examples, see the issues here: https://github.com/projecthydra/hydra-head/issues

data/doc/Home.md

@@ -0,0 +1,33 @@
+# Hydra Developer Wiki
+
+The projecthydra gem is a container gem which locks major version dependencies for a complete release of the hydra framework.  Requiring this gem or including it in your Gemfile will load or install a coherent set of hydra gems developed and tested for interoperability.  Developers requiring the most current functionality may choose to omit this gem and build their gem dependencies manually.
+
+This wiki is targeted towards developers who are implementing Hydra Heads. The [Duraspace wiki](http://wiki.duraspace.org/display/hydra/) has information discussing the Hydra architecture. There's also information for new and potential adopters on the [project web site](http://projecthydra.org).
+
+## Getting Started
+
+- **Tutorial:** [[Dive into Hydra]]
+- **Tutorial:** [Tame Your XML With OM](https://github.com/projecthydra/om/wiki/Tame-your-XML-with-OM)
+- **Tutorial:** [Access Controls with Hydra](https://github.com/projecthydra/hydra-head/wiki/Access-Controls-with-Hydra)
+
+
+## Documentation
+
+- [Developer documentation](https://github.com/projecthydra/hydra/wiki/For-Developers)
+- [Technical Framework and its Parts](https://wiki.duraspace.org/display/hydra/Technical+Framework+and+its+Parts)
+- [API Documentation](http://rdoc.info/github/projecthydra/hydra-head/)
+- [[Rake Tasks in Hydra Head]]
+- [Understanding Hydra Access Controls](https://github.com/projecthydra/hydra-head/wiki/Access-Controls)
+- [Filtering Search Results With Hydra Access Controls](https://github.com/projecthydra/hydra-head/wiki/Filtering-search-results-with-hydra-access-controls)
+- [File Uploads](https://github.com/projecthydra/hydra-head/wiki/File-uploads)
+- [File Downloads](https://github.com/projecthydra/hydra-head/wiki/File-downloads)
+- [[Configuring Solr and Fedora]]
+- [Deployment Hardware](https://wiki.duraspace.org/display/hydra/Deployment+Hardware+Information)
+- [[Migration Notes]]
+
+
+### Reference for Hydra Contributors/Committers
+
+If you are making changes to the hydra-head code itself, you will want to read
+
+- [How to Contribute](https://github.com/projecthydra/hydra/blob/master/CONTRIBUTING.md)

data/doc/Lesson:-Define-Relationships-Between-Objects.md

@@ -0,0 +1,127 @@
+This lesson is known to work with hydra version 6.1.0.   
+_Please update this wiki to reflect any other versions that have been tested._
+
+# Goals
+* Set up Models to represent relationships between different types of objects
+* Create and modify relationships between objects
+
+# Explanation
+Now that we have created a model for Books, we will create a separate model for Pages and set a relationship between the two models indicating that any Book can have many Pages and Pages know what Book they belong to.
+
+The syntax for declaring relationships between ActiveFedora models is the same syntax used by ActiveRecord.  It's called the ActiveModel syntax.  Underneath the hood, the two libraries implement relationships in very different ways.  ActiveRecord uses relational database techniques like foreign keys and join tables while ActiveFedora puts this information into RDF relationships in the RELS-EXT datastreams of your Fedora objects. In both cases you can use the ActiveRecord methods to handle relationships.
+
+# Steps
+
+### Step 1: Create an OM Terminology for Page metadata
+
+Next we're going to add a Page model.  We'll start by creating another simple metadata datastream.  This time open ```app/models/datastreams/page_metadata.rb``` and add this content:
+```ruby
+class PageMetadata < ActiveFedora::OmDatastream
+
+  set_terminology do |t|
+    t.root(path: "fields")
+    t.number index_as: :stored_searchable, type: :integer
+    t.text index_as: :stored_searchable
+
+  end
+
+  def self.xml_template
+    Nokogiri::XML.parse("<fields/>")
+  end
+end
+
+```
+
+### Step 2: Create a Page model and make Pages aware of which Book they belong to
+
+Then we'll build a Page model that uses the datastream. Open ```app/models/page.rb``` and paste this in:
+
+```ruby
+class Page < ActiveFedora::Base
+  has_metadata 'descMetadata', type: PageMetadata
+
+  belongs_to :book, :property=> :is_part_of
+
+  has_attributes :number, datastream: 'descMetadata', multiple: false
+  has_attributes :text, datastream: 'descMetadata', multiple: false
+  
+end
+```
+
+This is very similar to how our Book class looks, with the exception of the line ```belongs_to :book```.  This establishes a relationship between the book and page model nearly the same as you would do with ActiveRecord.  In ActiveFedora, we have to add the :property attribute as well.  Relationships are stored as RDF within the RELS-EXT datastream.  The :property is actually an RDF predicate. 
+
+### Step 3: Make Books aware of their Pages
+
+Let's edit the Book class and add the other half of the relationship:
+
+```ruby
+  # within app/models/book.rb
+  has_many :pages, :property=> :is_part_of
+```
+
+### Step 4: In the Console, manipulate relationships between Book and Page objects
+
+Save your changes and then reopen the rails console. Now we ought to be able to create some associations.
+
+```ruby
+b = Book.find("changeme:1")
+ => #<Book pid:"changeme:1", title:"Anna Karenina", author:"Tolstoy, Leo"> 
+p = Page.new(number: 1, text: "Happy families are all alike; every unhappy family is unhappy in its own way.")
+ => #<Page pid:"", number:1, text:"Happy families are all alike; every unhappy family is unhappy in its own way."> 
+p.book = b
+ => #<Book pid:"changeme:1", title:"Anna Karenina", author:"Tolstoy, Leo"> 
+p.save
+ => true 
+b.pages
+ => [#<Page pid:"changeme:2", number:1, text:"Happy families are all alike; every unhappy family is unhappy in its own way.">] 
+```
+
+### Step 5: Look at the RDF (if you want to)
+
+**Note:** If you don't know what RDF is and don't care to know, you can skip this step.
+
+Let's look at the RDF that active-fedora uses to represent these relationships.  This metadata is written into the RELS-EXT datastream of your objects.  To see that content, either output it on the command line like this:
+
+```ruby
+puts p.datastreams["RELS-EXT"].to_rels_ext
+```
+Alternatively, look at the datastream in your browser at [http://localhost:8983/fedora/objects/changeme:2/datastreams/RELS-EXT/content](http://localhost:8983/fedora/objects/changeme:2/datastreams/RELS-EXT/content)  (You might need to change the pid in the URL if your page's pid isn't changeme:2)
+
+Either way, you should see RDF that looks like this:
+
+```
+<?xml version="1.0" encoding="UTF-8"?>
+<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:ns0="info:fedora/fedora-system:def/model#" xmlns:ns1="info:fedora/fedora-system:def/relations-external#">
+  <rdf:Description rdf:about="info:fedora/changeme:2">
+    <ns0:hasModel rdf:resource="info:fedora/afmodel:Page"/>
+    <ns1:isPartOf rdf:resource="info:fedora/changeme:1"/>
+  </rdf:Description>
+</rdf:RDF>
+```
+
+As you can see, it is creating rdf assertions of `info:fedora/fedora-system:def/relations-external#isPartOf` `info:fedora/changeme:1` and `info:fedora/fedora-system:def/model#hasModel` `info:fedora/afmodel:Page`.  
+
+The model assertion is created automatically based on the name of your ActiveFedora model (in this case, Page), but how did ActiveFedora know to use the predicate `info:fedora/fedora-system:def/relations-external#isPartOf` when your `belongs_to` specified a property called :is_part_of?
+
+In other words, how did we get from 
+
+```ruby
+belongs_to :book, :property=> :is_part_of
+```
+
+to ``info:fedora/fedora-system:def/relations-external#isPartOf`?
+
+The answer is that active-fedora has a config file that it uses to look up RDF predicates based on the property name you specify in your model.  By default, these predicates are read from the active-fedora gem, but you can override them by creating your own copy in config/predicate_mappings.yml in your own application.  To see the default mappings, look at active-fedora's default [predicate mappings YAML file] (https://github.com/projecthydra/active_fedora/blob/master/config/predicate_mappings.yml) on github.
+
+### Step 6: Commit your changes
+
+Now that we've added page relationships, it's a great time to commit to git:
+
+```bash
+$> git add .
+$> git commit -m "Created a book page model with relationship to the book model"
+```
+
+# Next Step
+Go on to [[Lesson: Adding Content Datastreams]] or 
+explore other [Dive into Hydra](Dive into Hydra#Bonus) tutorial bonus lessons.

data/doc/Lesson:-Generate-Rails-Scaffolding-for-Creating-and-Editing-Books.md

@@ -0,0 +1,167 @@
+This Tutorial is known to work with hydra version 6.1.0.  
+_Please update this wiki to reflect any other versions that have been tested._
+
+# Goals
+
+- Understand the difference between unique (single-value) and multi-valued metadata fields
+- Learn how to make modifications to the views which support CRUD (Create, Read, Update, Delete) on objects in your repo
+
+# Explanation
+
+This lesson walks you through modifying the "Title" field in your book model to make it either single- or multi-valued.  The lesson then walks through the changes necessary to modify views to read, create, and edit your updated metadata model.
+
+# Steps
+
+
+### Step 1: Set up Rails Scaffolding for creating and editing Books
+
+We will use the Rails scaffold generator to set up the routes, Controller and Views we need in order to CRUD books.  
+
+**Note:** If you are not familiar with the ideas of Controllers, Views and routes, or aren't familiar with the Rails scaffold generator, go through the [Railsbridge Curriculum](http://curriculum.railsbridge.org/curriculum/curriculum) and then come back to this lesson.  You might also want to read the [Getting Started with Rails](http://guides.rubyonrails.org/getting_started.html) guide.
+
+Tell the generator to build scaffolding for the Book model and make it assume books have `title` and `author` attributes like the ones we set up earlier in [[Lesson: build a book model]].
+```text
+rails generate scaffold Book title:string author:string
+```
+
+When it asks you whether to overwrite `app/models/book.rb`, enter `n` and hit enter.  
+
+Depending on the specific version of rails you are running the generator creates a few things that we don't want in the `test` and `db` directories.  Delete them with the `git clean` command.
+
+```bash
+$ git clean -df test db
+```
+You'll see output something like this:
+```text
+Removing db/migrate/20130417230046_create_books.rb
+Removing test/fixtures/books.yml
+Removing test/functional/books_controller_test.rb
+Removing test/unit/book_test.rb
+Removing test/unit/helpers/
+```
+
+### Step 2: Commit your work
+
+```text
+git add .
+git commit -m "Ran scaffold generator"
+```
+
+### Step 3: Run the server & Explore
+
+Run the `rails server` and visit [[http://localhost:3000/books]]
+
+Explore the pages for creating, editing and showing Books.  
+
+### Step 4: Make the Display view show Authors as a multi-valued field
+
+Open `app/models/book.rb` and edit the unique setting to be 'false':
+
+```ruby
+   has_attributes :author, datastream: 'descMetadata', multiple: true
+```
+
+Now you need to tell your hydra application how to display multivalued fields in the 'show' (Display) view for this model. 
+In `app/views/books/show.html.erb` find the lines that display the author field.
+```erb
+  <p>
+    <b>Author:</b>
+    <%= @book.author %>
+  </p>
+```
+
+We want to make these lines iterate over the values returned by `@book.author` and put them in a list
+```erb
+<p>
+  <b>Author(s):</b>
+  <ul>
+    <%- @book.author.each do |author|%>
+      <li><%= author %></li>
+    <%- end %>
+  </ul>
+</p>
+```
+
+Save the file and refresh the Show view for a book.  Now authors show up as a list of values.
+
+### Step 5: Allow Create and Update views to display Authors as a multi-valued field
+
+The `_form` partial defines the guts of the form that's used in both the `new` (Create) view and the `edit` (Update) view.  That makes our lives simpler because we only have to update that one file to fix both pages!
+
+In `app/views/books/_form.html.erb` find the lines that display the author field.
+
+```erb
+<div class="field">
+    <%= f.label :author %><br />
+    <%= f.text_field :author %>
+</div>
+```
+
+Replace those lines with something that iterates over the values from `@book.author` and displays a text_field tag for each of them.  Note that the @name attribute will be set to "book[author][]".  The trailing `[]` in the name tells Rails that this is a multivalued field that should be parsed as an Array.
+```erb
+  <%= f.label :author, "Authors" %>
+  <% @book.author.each do |author| %>
+    <div class="field">
+      <%= text_field_tag "book[author][]", author %>
+    </div>
+  <% end %> 
+```
+
+This handles displaying existing author values, but what about setting the author value in the first place?  If there are no values in the array, no fields are going to be displayed.  As a stop-gap, we can add a conditional clause that displays an empty text_field when the array is empty.
+
+```erb
+  <%= f.label :author, "Authors" %>
+  <% @book.author.each do |author| %>
+    <div class="field">
+      <%= text_field_tag "book[author][]", author %>
+    </div>
+  <% end %> 
+  <%- if @book.author.empty? %>
+    <div class="field">
+      <%= text_field_tag "book[author][]", nil %>
+    </div>
+  <%- end %>
+```
+
+*Note:* This still doesn't cover the case where you want to _add_ more than one Author to a Book.  That goes beyond the scope of this tutorial because it requires javascript (or a multi-page workflow).
+
+> #### Rails 4-only step
+>
+> Update the `book_params` method in `app/controllers/books_controller.rb` from
+> ```ruby
+>     def book_params
+>       params.require(:book).permit(:title, :author)
+>     end
+> ```
+> to
+> ```ruby
+>     def book_params
+>       params.require(:book).permit(:title, :author=>[])
+>     end
+> ```
+
+### Step 6: Try out multiple authors
+
+Start up the rails console and run the following commands to add a second author to our book.
+
+```ruby
+b = Book.find('changeme:1')
+b.author += ['Some other author']
+b.save
+```
+
+Visit [[http://localhost:3000/books]] again and see that multiple authors show up and that you can edit them.
+
+### Step 7: Commit your Work
+
+```text
+git add .
+git commit -m "Handling multivalued author fields"
+```
+
+### Step 8: [Optional] Enhance the display of Title fields
+
+Based on the concepts in steps 1-7, determine whether you want 'Title' to display as a single or multi-valued field and make appropriate edits to the 'show' view and '_form' partial on your own.
+
+# Next Step
+Proceed to [[Lesson: Set up your Rails Application to use RSpec]] or explore other [Dive into Hydra](Dive into Hydra#Bonus) tutorial bonus lessons.