hydra 6.2.0.rc1 → 6.2.0

data/doc/Lesson:-Reading-Hydra-rightsMetadata-XML.md

@@ -0,0 +1,87 @@
+This Tutorial is known to work with hydra-head version 6.0.0..  
+_Please update this wiki to reflect any other versions that have been tested._
+
+# Steps
+
+Given a book whose permissions look like this:
+```text
+puts book.permissions
+{:type=>"group", :access=>"discover", :name=>"group2"}
+{:type=>"group", :access=>"read", :name=>"group3"}
+{:type=>"group", :access=>"read", :name=>"group9"}
+{:type=>"group", :access=>"read", :name=>"group8"}
+{:type=>"user", :access=>"read", :name=>"user3"}
+{:type=>"user", :access=>"edit", :name=>"bob1"}
+{:type=>"user", :access=>"edit", :name=>"sally2"}
+```
+
+The permissions will be written into the rightsMetadata datstream like so
+```xml
+puts book.rightsMetadata.to_xml
+<rightsMetadata xmlns="http://hydra-collab.stanford.edu/schemas/rightsMetadata/v1" version="0.1">
+  <copyright>
+    <human type="title"/>
+    <human type="description"/>
+    <machine type="uri"/>
+  </copyright>
+  <access type="discover">
+    <human/>
+    <machine>
+      <group>group2</group>
+    </machine>
+  </access>
+  <access type="read">
+    <human/>
+    <machine>
+      <group>group3</group>
+      <group>group9</group>
+      <group>group8</group>
+      <person>user3</person>
+    </machine>
+  </access>
+  <access type="edit">
+    <human/>
+    <machine>
+      <person>bob1</person>
+      <person>sally2</person>
+    </machine>
+  </access>
+  <embargo>
+    <human/>
+    <machine/>
+  </embargo>
+</rightsMetadata>
+```
+
+If we remove the nodes that aren't relevant to this lesson, the XML looks like this:
+
+```xml
+<rightsMetadata xmlns="http://hydra-collab.stanford.edu/schemas/rightsMetadata/v1" version="0.1">
+  <access type="discover">
+    <machine>
+      <group>group2</group>
+    </machine>
+  </access>
+  <access type="read">
+    <machine>
+      <group>group3</group>
+      <group>group9</group>
+      <group>group8</group>
+      <person>user3</person>
+    </machine>
+  </access>
+  <access type="edit">
+    <machine>
+      <person>bob1</person>
+      <person>sally2</person>
+    </machine>
+  </access>
+</rightsMetadata>
+```
+
+As you can see, group ids are put into `<group>` nodes and user ids are put into `<person>` nodes.  The type of access being granted is decided by the @type attribute on the `<access>` nodes.
+
+The intermediary `<machine>` node is meant to allow you to insert human-readable information into the 'access/human' node while inserting the machine-readable assertions into 'access/machine' node.
+
+# Next Step
+Go on to [[Lesson: Indexing Hydra Rights Metadata into Solr]] or return to the [[Access Controls with Hydra]] tutorial.

data/doc/Lesson:-Use-Hydra-Access-Controls-to-Control-Access-to-Blacklight-show-Pages.md

@@ -0,0 +1,37 @@
+This Tutorial is known to work with hydra-head version 6.0.0.  
+_Please update this wiki to reflect any other versions that have been tested._
+
+# Goals
+
+# Explanation
+
+# Steps
+
+### Step 1: Enforce Show permissions on Blacklight search results
+
+When we turned off access controls as part of the [[Dive into Hydra]] tutorial, we commented out two lines.  The first line was turning on gated discovery.  We covered that in the previous lesson.  The other line was telling Blacklight to prevent unauthorized access to `show` views for items from your searches.  Let's enable that filter and see what it does.
+
+Open app/controllers/catalog_controller.rb and find these lines
+```ruby
+  # These before_filters apply the hydra access controls
+  # before_filter :enforce_show_permissions, :only=>:show
+```
+
+Uncomment the line with the `before_filter`
+```ruby
+  # These before_filters apply the hydra access controls
+  before_filter :enforce_show_permissions, :only=>:show
+```
+
+### Step 2: Test the enforcement of Show permissions on Blacklight search results
+
+In your browser, log into the application as yourself, run a search, and click on the link to a book that you only have `discover` access to.  Depending on what experiments you've done based on the previous lesson, you might have to go into the `rails console` and either create a new book that you have discover access to or modify an existing book to give you discover access.  
+
+You should have been redirected back to the search results page with a message reading _"You do not have sufficient access privileges to read this document, which has been marked private."_
+
+**Note:** For this example, it's important that you to _only_ have discover access (not `read` or `edit`) and that none of the groups you belong to have `read` or `edit` access either.  If you or one of your groups has `read` or `edit` access then you will see the book's `show` page instead of being redirected by the access controls.
+
+In the `rails console`, grant yourself 'read' or 'edit' access to the book and save the book.  Then in the browser you will be able to visit the `show` page for that book instead of being redirected like before.
+
+# Next Step
+Go on to [[Lesson: Use Hydra Access Controls and CanCan to decide whether to render a page]] or return to the [[Access Controls with Hydra]] tutorial.

data/doc/Lesson:-Using-Hydra-Access-Controls-and-CanCan-to-conditionally-render-part-of-a-page.md

@@ -0,0 +1,29 @@
+This Tutorial is known to work with hydra-head version 6.0.0.  
+_Please update this wiki to reflect any other versions that have been tested._
+
+# Goals
+
+# Explanation
+
+# Steps
+
+### Step: Use `can?` to conditionally render html on a page
+
+In `app/views/books/show.html.erb` find the code that's displaying the "Edit" and "Back" links at the bottom of the page.
+```erb
+<%= link_to 'Edit', edit_book_path(@book) %> |
+<%= link_to 'Back', books_path %>
+```
+
+Use an `if ... end` clause to only show the "Edit" link if the current user has permission to edit the current book.
+```erb
+<%- if can?(:edit, @book) %>
+  <%= link_to 'Edit', edit_book_path(@book) %> |
+<%- end %>
+<%= link_to 'Back', books_path %>
+```
+
+Now go into the `rails console` and give yourself `edit` access to one book but only `read` access for another.  Look at the show views for the two books.  You should see the "Edit" link on the book that you have permission to edit and you should not see the "Edit" link for the book that you do not have permission to edit.
+
+# Next Step
+Return to the [[Access Controls with Hydra]] tutorial.

data/doc/Lesson:-add-the-Hydra-dependencies.md

@@ -0,0 +1,28 @@
+This lesson is known to work with hydra (gem) version 6.1.0.   
+_Please update this wiki to reflect any other versions that have been tested._
+
+# Goals
+* Add the Hydra software to your application's list of dependencies
+* Use bundler to install dependencies
+
+# Explanation 
+
+In order to take advantage of the Hydra code and features in your application, you need to tell the application where to find that code and which versions of that code to use.  Rails uses a tool called [bundler](http://bundler.io/) to track dependencies.  Bundler looks in the file called `Gemfile` to know what you want installed.
+
+# Steps
+
+Open up ```Gemfile``` in your editor.   We're going to add the following lines:
+
+```ruby
+gem 'hydra', require: 'hydra6'
+```
+
+This declares our application to have a dependency on the hydra6 release version of the hydra-gem and ensures that the hydra-head gem gets included (required) correctly. This includes a dependency for the jettywrapper gem (installed automatically). The jettywrapper gem is used to install and configure a preconfigured instance of jetty that loads and runs local development instances of Fedora and Solr for you to run and test your application against.
+
+Now we save the file and install the dependencies by running bundler:
+```text
+$ bundle install
+```
+
+# Next Step
+Go on to [[Lesson: Run the Hydra generator]] or return to the [[Dive into Hydra]] page.

data/doc/Lesson:-adding-content-datastreams.md

@@ -0,0 +1,60 @@
+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
+* Add "file-bearing" Datastreams to models and objects
+* See where files are stored in Fedora objects and how to retrieve them
+
+# Explanation
+
+So far, we've only added datastreams that bear metadata.  Let's add a datastream that has some content to it.  For example, this could be a content datastream in our book model that is an image of the book's cover, or a datastream added to the page model that is an image or pdf of that actual page.
+
+In this case, we'll add a file datastream where we can store a pdf of a page.
+
+# Steps
+
+### Step 1: Add a "pageContent" file datastream to the Page model
+
+In our Page model ```app/models/page.rb```, we'll add the following line underneath our descMetadata datastream:
+
+```ruby
+has_file_datastream "pageContent"
+```
+
+Now we have a datastream called "pageContent" that can hold any kind of file we wish to add to it.  
+
+### Step 2: In the console, add a file to a Page object and save it
+
+To add the file to one of our page objects, open up the console again:
+
+```ruby
+ > p = Page.find("changeme:2")
+ => #<Page pid:"changeme:2", number:[1], text:["Happy families are all alike; every unhappy family is unhappy in its own way."]> 
+ > p.datastreams.keys
+ => ["DC", "RELS-EXT", "descMetadata", "pageContent"] 
+```
+
+Now you're ready to add the file.  Choose a file on your computer that you want to add as the "pageContent".  In the lines below we're pretending that the path to the file is "/Users/adamw/Desktop/page1.pdf".  Replace that with the correct local path for the file you want to use.
+
+```ruby
+ > p.pageContent.content = File.open("/Users/adamw/Desktop/page1.pdf")
+ => #<File:/Users/adamw/Desktop/page1.pdf> 
+ > p.save
+ => true
+```
+
+### Step 3: See where the file Datastream was saved in Fedora
+
+Now if you go to [[http://localhost:8983/fedora/objects/changeme:2/datastreams]], you'll see the pageContent datastream in Fedora.  Following the links to it will allow us to view or download the file we've added.
+
+### Step 4: Commit your changes
+
+Now that we've added a content datastream, it's a great time to commit to git:
+
+```bash
+$> git add .
+$> git commit -m "Created a content datastream"
+```
+
+# Next Step
+Proceed to [[Lesson: Generate Rails Scaffolding for Creating and Editing Books]] or explore other [Dive into Hydra](Dive into Hydra#bonus) tutorial bonus lessons.

data/doc/Lesson:-build-a-book-model.md

@@ -0,0 +1,262 @@
+This lesson is known to work with hydra release version 6.1.0.   
+_Please update this wiki to reflect any other versions that have been tested._
+
+# Goals
+* Define a simple OM (Opinionated Metadata) Terminology for Book Metadata that we will track as XML Datastreams
+* Start the Rails console and run code interactively in the console
+* Create Datastream objects that use your OM Terminology
+* Define an ActiveFedora Model for Book objects 
+* Declare a Datastream called descMetadata on your Book model and make it use your Book Metadata Terminology
+* Delegate methods from Book objects to their descMetadata Datastream
+* Create Book objects that use your Book Model
+* See how an object has been indexed into Solr
+* See how & where objects and metadata are stored in Fedora
+* Use OM to Manage how your Metadata is indexed in Solr
+* Re-index objects into Solr (update Solr based on any changes to an object, its Model, or the OM Terminologies it uses)
+
+# Explanation
+In Fedora an object can have many 'datastreams' which are either content for the object or metadata about the object. We are going to create a 'book' object.  This object will have a metadata datastream which will contain some XML that describes the properties of the book.  We'll call this datastream 'descMetadata'.  You are free to call it whatever you like, but 'descMetadata' is a loose convention that stands for 'descriptive metadata'.
+
+Once you've created an object and saved it in Fedora, you also want to be able to search for it in Solr.  ActiveFedora and OM make it easy to get your metadata into Solr and manage if/when/how your metadata is indexed. 
+
+# Steps
+
+### Step 1: Create an OM Terminology for Book Metadata
+
+First we'll create a Ruby class that represents this descriptive metadata.  Make a new directory for our datastreams by typing in 
+```bash
+$> mkdir app/models/datastreams
+```
+
+Now we'll create a file called `app/models/datastreams/book_metadata.rb`
+
+Paste the following code into that file:
+
+```ruby
+class BookMetadata < ActiveFedora::OmDatastream
+
+  set_terminology do |t|
+    t.root(path: "fields")
+    t.title
+    t.author
+  end
+
+  def self.xml_template
+    Nokogiri::XML.parse("<fields/>")
+  end
+end
+```
+
+This class extends from OmDatastream. OM is a gem that allows us to describe the format of an xml file and access properties. We are using OM by calling the `set_terminology` method.  The xml_template method tells OM how to create a new xml document for this class. 
+
+**Tip:** If you want to learn about OM Terminologies and how they work, visit the [Tame your XML with OM](https://github.com/projecthydra/om/wiki/Tame-your-XML-with-OM) Tutorial.
+
+### Step 2: Start the Rails console
+
+Let's take a look at how this class works.  We'll start the rails console by typing 
+
+```bash
+$> rails console
+```
+
+You should see something like `Loading development environment (Rails 3.2.11)`.  Now you're in a "[REPL](http://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop)", or *interactive ruby console* that has all of your Rails application's code and configuration loaded. 
+
+### Step 3: In the console, create Datastream objects that use your OM Terminology
+
+Let's create a new BookMetadata instance. I've shown the expected output after each command:
+
+```text
+d = BookMetadata.new
+ => #<BookMetadata @pid="" @dsid="" @controlGroup="X" changed="false" @mimeType="text/xml" > 
+d.title = "ZOIA! Memoirs of Zoia Horn, Battler for the People's Right to Know."
+ => "ZOIA! Memoirs of Zoia Horn, Battler for the People's Right to Know." 
+d.author = "Horn, Zoia"
+ => "Horn, Zoia" 
+d.to_xml
+ => "<fields>\n  <title>ZOIA! Memoirs of Zoia Horn, Battler for the People's Right to Know.</title>\n  <author>Horn, Zoia</author>\n</fields>"
+```
+
+Once you're done, exit the console by typing ```exit```
+
+
+### Step 4: Define a Book Model
+
+Now let's, create a model that uses this datastream.  Create a new file at `app/models/book.rb`. We'll paste in this code:
+
+```ruby
+class Book < ActiveFedora::Base
+  has_metadata 'descMetadata', type: BookMetadata
+
+  has_attributes :title, datastream: 'descMetadata', multiple: false
+  has_attributes :author, datastream: 'descMetadata', multiple: false
+
+end
+```
+
+We've defined our Book model to use the BookMetadata for its datastream called 'descMetadata'.  We're telling the model to use the descMetadata as the delegate for the properties 'title' and 'author'.  We are also telling Active Fedora to treat these attributes as single values rather than as multi-valued arrays.
+
+### Step 5: In the console, create Datastream objects that use your OM Terminology
+
+Now we'll open the `rails console` again and see how to work with our book.
+
+```text
+b = Book.create(title: 'Anna Karenina', author: 'Tolstoy, Leo')
+ => #<Book pid:"changeme:1", title:["Anna Karenina"], author:["Tolstoy, Leo"]> 
+```
+
+We've created a new Book object in the repository.  You can see that it has a pid (Fedora Commons persistence identifier) of 'changeme:1'.  Because you set title and author to delegate to the descMetadata datastream, they are stored in that datastream's XML and can be accessed either through the delegated methods on the Book, or by going specifically to the datastream. 
+
+
+```text
+b.descMetadata
+ => #<BookMetadata @pid="changeme:1" @dsid="descMetadata" @controlGroup="M" changed="false" @mimeType="text/xml" > 
+b.title
+ => "Anna Karenina" 
+b.author
+ => "Tolstoy, Leo"
+b.descMetadata.title
+ => ["Anna Karenina"] 
+b.descMetadata.author
+ => ["Tolstoy, Leo"] 
+```
+
+
+### Step 6: See what your Book objects look like in Fedora and Solr
+
+If we go to [[http://localhost:8983/fedora/objects/changeme:1]] we should see what it looks like in fedora.  Note especially that the xml datastream has been ingested [[http://localhost:8983/fedora/objects/changeme:1/datastreams/descMetadata/content]].  The content of that datastream should look like this in your browser:
+
+```xml
+<fields>
+  <title>Anna Karenina</title>
+  <author>Tolstoy, Leo</author>
+</fields>
+```
+
+Let's also see that this book has been ingested into the Solr search index. [[http://localhost:8983/solr/select?q=changeme:1]].  It should look like the sample below.  Note that, at this point, the title and author have not been stored in solr.  You only get fields like `system_create_dtsi`, `system_modified_dtsi`, `id`, `object_profile_ssm`, and `has_model_ssim`.  In the next step we will modify our BookMetadata datastream to add the book metadata to the solr document.
+
+```xml
+<?xml version="1.0"?>
+<response>
+  <lst name="responseHeader">
+    <int name="status">0</int>
+    <int name="QTime">3</int>
+    <lst name="params">
+      <str name="q">changeme:4</str>
+    </lst>
+  </lst>
+  <result name="response" numFound="1" start="0" maxScore="0.05991731">
+    <doc>
+      <date name="system_create_dtsi">2013-05-06T16:22:39Z</date>
+      <date name="system_modified_dtsi">2013-05-06T16:22:39Z</date>
+      <arr name="active_fedora_model_ssim">
+        <str>Book</str>
+      </arr>
+      <str name="id">changeme:4</str>
+      <arr name="object_profile_ssm">
+        <str>{"datastreams":{"RELS-EXT":{"dsLabel":"Fedora Object-to-Object Relationship Metadata","dsVersionID":"RELS-EXT.0","dsCreateDate":"2013-05-06T16:22:40Z","dsState":"A","dsMIME":"application/rdf+xml","dsFormatURI":null,"dsControlGroup":"X","dsSize":277,"dsVersionable":true,"dsInfoType":null,"dsLocation":"changeme:4+RELS-EXT+RELS-EXT.0","dsLocationType":null,"dsChecksumType":"DISABLED","dsChecksum":"none"},"descMetadata":{"dsLabel":null,"dsVersionID":"descMetadata.0","dsCreateDate":"2013-05-06T16:22:41Z","dsState":"A","dsMIME":"text/xml","dsFormatURI":null,"dsControlGroup":"M","dsSize":81,"dsVersionable":true,"dsInfoType":null,"dsLocation":"changeme:4+descMetadata+descMetadata.0","dsLocationType":"INTERNAL_ID","dsChecksumType":"DISABLED","dsChecksum":"none"},"rightsMetadata":{}},"objLabel":null,"objOwnerId":"fedoraAdmin","objModels":["info:fedora/fedora-system:FedoraObject-3.0"],"objCreateDate":"2013-05-06T16:22:39Z","objLastModDate":"2013-05-06T16:22:39Z","objDissIndexViewURL":"http://localhost:8983/fedora/objects/changeme%3A4/methods/fedora-system%3A3/viewMethodIndex","objItemIndexViewURL":"http://localhost:8983/fedora/objects/changeme%3A4/methods/fedora-system%3A3/viewItemIndex","objState":"A"}</str>
+      </arr>
+      <arr name="has_model_ssim">
+        <str>info:fedora/afmodel:Book</str>
+      </arr>
+      <date name="timestamp">2013-05-06T16:22:58.397Z</date>
+      <float name="score">0.05991731</float>
+    </doc>
+  </result>
+  <lst name="facet_counts">
+    <lst name="facet_queries"/>
+    <lst name="facet_fields">
+      <lst name="active_fedora_model_ssi"/>
+      <lst name="object_type_si"/>
+    </lst>
+    <lst name="facet_dates"/>
+    <lst name="facet_ranges"/>
+  </lst>
+</response>
+```
+### Step 7: See how your Book metadata are indexed into Solr
+
+
+The to_solr method is what generates the solr document for your objects and their datastreams.  To see the full solr document for the book we created, call
+
+```text
+b.to_solr
+```
+
+To see just the part of the solr document that comes from the descMetadata datastream (which has our book title and author), call
+
+```text
+b.descMetadata.to_solr
+ => {} 
+```
+
+As you can see, the descMetadata datastream is returning an empty Hash, meaning that it isn't indexing the author and title values.
+
+### Step 8: Change how your Book metadata are indexed into Solr
+
+To make the BookMetadata Terminology index the author and title fields, you need to reopen `app/models/datastreams/book_metadata.rb` and change the terminology section to look like this:
+
+```ruby
+  set_terminology do |t|
+    t.root(path: "fields")
+    t.title(index_as: :stored_searchable)
+    t.author(index_as: :stored_searchable)
+  end
+```
+
+**Note:** Because we have made changes to our Ruby code that we want to use, we need to restart the Rails console so that it will reload all of the code, including our latest changes.
+
+Now, **restart the rails console** and we can load the object we previously created:
+
+```text
+b = Book.find('changeme:1')
+ => #<Book pid:"changeme:1", title:"Anna Karenina", author:"Tolstoy, Leo">
+```
+
+Check and see that to_solr includes the title and author fields.
+
+```text
+b.descMetadata.to_solr
+ => {"title_tesim"=>["Anna Karenina"], "author_tesim"=>["Tolstoy, Leo"]}
+```
+Now when you call `.to_solr` on a BookMetadata datastream it returns a solr document with fields named `title_tesim` and `author_tesim` that contain your title and author values.  Those are the field names that we will add to Blacklight's queries in [[Lesson: Make Blacklight Return Search Results]].
+
+
+### Step 9: Re-index an object in Solr
+
+Now we'll call the ```update_index``` method, which republishes the Solr document using the changes we've made.
+
+```text
+b.update_index
+ => {"responseHeader"=>{"status"=>0, "QTime"=>25}} 
+```
+
+If you refresh the document result from solr ([[http://localhost:8983/solr/select?q=changeme:1]]) you should see that these fields have been added to the solr_document:
+
+```xml
+<arr name="title_tesim">
+  <str>Anna Karenina</str>
+</arr>
+<arr name="author_tesim">
+  <str>Tolstoy, Leo</str>
+</arr>
+```
+
+**Aside:** The strange suffixes on the field names are provided by [solrizer](http://github.com/projecthydra/solrizer). You can read about them in the solrizer documentaton. In short, the **_tesim** suffix tells Solr to treat the values as _**t**ext_ in the _**e**nglish_ language that should be _**s**tored_, _**i**ndexed_ and allowed to be _**m**ultivalued_. This _tesim suffix is a useful catch-all that gets your searches working predictably with minimal fuss. As you encounter cases where you need to index your content in more nuanced ways, there are ways to change these suffixes in order to achieve different results in Solr.
+
+#### Why doesn't the Book show up in Blacklight?
+
+Now your object is indexed properly, but it **won't show up in Blacklight's search results** until you've turned off access controls and added the appropriate fields to Blacklight's queries.  We cover those in the next 2 lessons.
+
+### Step 10: Commit your changes
+
+Now that we've got our model working, it's a great time to commit to git:
+
+```bash
+$> git add .
+$> git commit -m "Created a book model and a datastream"
+```
+
+# Next Step
+Go on to [[Lesson: Turn Off Access Controls]] or return to the [[Dive into Hydra]] page.
+
+If you want to learn about OM Terminologies and how they work, visit the [Tame your XML with OM](https://github.com/projecthydra/om/wiki/Tame-your-XML-with-OM) Tutorial.