hydra 10.0.0 → 10.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3316a1268a42d22b946ab0a140025fd755d2f9eb
-  data.tar.gz: 3ab6ba8b2f8b06ef7bf5aa33c18debd59707c59c
+  metadata.gz: aed1dcdbcdfcda7120bdbdff2cd4f07b4f590c4c
+  data.tar.gz: 25983f2c12bdf3e5732a141d2cb1647996d1c03c
 SHA512:
-  metadata.gz: d72f79685687e9d9b8868ec3116cd396d3f14e45eaa80842db85bc0b739188e35c84697563a8d1b08eceb07f1a5ed4a4d02cb4a515a518d7e80776615971730f
-  data.tar.gz: 6e4f892d2dbec0541b7b26060a1c21ec524ee8839c5b66ffeb97ec815b99bbcf2ed32b8e118c271b56fec6be05d82ea65ddea055de0002947c18af22422b7756
+  metadata.gz: c3b32bb400ea408755552f468494588495a115762a85cb6849aecdccf749fc6edc1ea9be1981b2ab2078bb4b5961c50d2c14855e41add850ac0c4262ee19aeaa
+  data.tar.gz: fe7e6dcaf71c37ad11cf5f6ee2fb73793fd079a6c20da6ede157d7e857f60311c2b2e0b0381eb5738a8184c2e2bfa85480d62855a6029cc0698f26d0106a3e8a

data/doc/Dive-into-Hydra.md

@@ -1,57 +1,60 @@
-This tutorial is tested to work with [hydra](http://rubygems.org/gems/hydra) release version 7.0.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/) 2.1.1 (also works with 2.0.0)
-+ [rails](http://rubyonrails.org/)  ~>4.1.0  (also works with 3.2.x & 4.0.x)
-+ [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: Add the Hydra Dependencies]]
-1. [[Lesson: Install hydra-jetty]]
-1. [[Lesson: Start the Application & Search for Results]]
-1. [[Lesson: Build a Book Model]]
-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]]  
-
-# 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)
+This tutorial is tested to work with [hydra](http://rubygems.org/gems/hydra) release version 9.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 to successfully complete this tutorial:
++ [Ruby](http://www.ruby-lang.org/en/) >= 2.1
++ [Rubygems](http://rubygems.org/) >= 2.5.2
++ [Rails](http://rubyonrails.org/)  ~> 4.2
++ [git](http://git-scm.com/)
++ [Java](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html) Development Kit >= 8  
+
+> *Note:* these requirements are specific to this tutorial, please check the Hydra README.md for additional version compatibility information.
+
+# Goals
+* Create a working Hydra Head
+* Get development instances of Solr & Fedora installed and running
+* Start & Stop the development instance of the Application
+* Define Models for Content to put into your Hydra Head (in this case Books, Manuscripts 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
+* Start Using Git to Track Code Changes
+
+# Steps/Lessons
+1. [[Lesson - Generate a Rails Application]]
+1. [[Lesson - Add the Hydra Dependencies]]
+1. [[Lesson - Start FCRepo and Solr]]
+1. [[Lesson - Start the Application & Search for Results]]
+1. [[Lesson - Build a Book model with RDF]]
+1. [[Lesson - Build a Codex model with XML]]
+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 attached Files]]  
+1. [[Lesson - Generate Rails Scaffolding for Creating and Editing Books]]  
+
+# 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 want 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://avatars3.githubusercontent.com/u/109426?v=3&s=200)

data/doc/For-Developers.md

@@ -27,7 +27,6 @@ All of our code is hosted on Github in the [projecthydra](https://github.com/pro
     * [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)
 

data/doc/Hackfest-ideas.md

@@ -0,0 +1,18 @@
+Here are some projects we the community could get started if we had some time to hack:
+
+- Memory adapter for active fedora.
+- AngularJS editor (replacement/substitute for hydra-editor)
+- Put [Oargun](https://github.com/curationexperts/oargun) metadata into a plugin/add-on for Sufia
+- Linked Data Caching - Explore Apache Stanbol maybe?
+- A recipe for deploying the stack with Docker
+- Service wrapper for that can startup multiple services (e.g. Solr 5, Fedora 4, Marmotta?) with one command
+- Port the LDP gem to Hurley (from Faraday) https://github.com/lostisland/hurley
+- Bring sufia's various metadata forms into a state of consistency / uniformity (post-upload form, single file edit, batch edit all have different UX and present fields in different orders) 
+- Use Raptor (https://ruby-rdf.github.io/rdf-raptor/) to speed up ActiveFedora
+- Store ACLs as hash code resources. This should reduce the number of LDP requests.
+
+
+Past projects:
+- Extract the shared methods out of ActiveFedora::Base (Core) and ActiveFedora::File. Several commits around 24 June 2015 https://github.com/projecthydra/active_fedora/commit/bc551d68f81d9dc10f45f652cd01dba36a158897
+- Replace Sufia's queuing with ActiveJob (done for Sufia 7 / CurationConcerns)
+- Replace jetty_wrapper with solr_wrapper and fcrepo_wrapper (Spring 2016 dev retreat)

data/doc/Home.md

@@ -1,4 +1,5 @@
 # Hydra Developer Wiki
+(Please feel free to edit this wiki and help make it better - if you're not sure about changes, propose them on hydra-tech@googlegroups.com first)
 
 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.
 
@@ -21,13 +22,14 @@ This wiki is targeted towards developers who are implementing Hydra Heads. The [
 - [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]]
 - [[Hydra Recipes]] - short how-to articles
+- [[LDP Containers for the perplexed]]
 
 ### 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)
+- [[Hackfest ideas]]

data/doc/Hydra-Recipes.md

@@ -6,4 +6,8 @@
 
 [[Indexing non English content]] - if you are indexing non English content into Hydra, you may want to update your Solr config to take advantage of Solr's language specific stemming capabilities.
 
-[Uniqueness validator for ActiveFedora](https://gist.github.com/dchandekstark/f969ad21bf518c7cd3c5) - Inspired by the ActiveRecord uniqueness validator, with some limitations.
+[Uniqueness validator for ActiveFedora](https://gist.github.com/dchandekstark/f969ad21bf518c7cd3c5) - Inspired by the ActiveRecord uniqueness validator, with some limitations.
+
+[[Using rdf:resource within your models]] 
+
+[[Recipe: Add full text indexing to your app]]

data/doc/LDP-Containers-for-the-perplexed.md

@@ -0,0 +1,119 @@
+This document is a summary of the basic differences between the different kind of containers that Linked Data Platform (LDP) supports.
+
+LDP specifies three types of containers: 
+  1. Basic Container
+  2. Direct Container
+  3. Indirect Container. 
+
+This document describes the differences between the three types of containers by showing what triples are added by an LDP Server when adding a new element to each kind of container. 
+
+In particular we assume we have a fictitious blog entry (`/blog/entry1/`) and we want to add a comment to it. We start by showing what happens if the blog entry is a Basic Container, then we show what happens if the blog entry was instead a Direct Container, and lastly if it was an Indirect Container.
+
+This document assumes familiarity with concepts described in the LDP Spec (http://www.w3.org/TR/ldp/#ldpdc) and the examples described in the LDP Primer (http://www.w3.org/TR/ldp-primer/). If you haven't read those documents this document might not make much sense. However, if you read those documents and still have some doubts about the differences between the different kind of containers this document should help to clarify them.
+
+
+## Basic Container
+Assuming we have a **Basic Container** issuing an `HTTP GET /blog/entry1/` will return something like this:
+
+    </blog/entry1/> a ldp:Container .
+    </blog/entry1/> dc:title "First blog entry" .
+
+To add an object to this container (for example, a comment to this blog entry) we would issue an `HTTP POST /blog/entry1` with `Slug: comment1` which will result in 
+
+  1. A new resource created at `/blog/entry1/comment1`
+  2. A new triple (with predicate `ldp:contains`) added to `/blog/entry1/`
+
+Issuing an `HTTP GET /blog/entry1/comment1` will return the new resource created, something like this:
+
+    </blog/entry1/comment1/> a ldp:RDFSource .
+    </blog/entry1/comment1/> dc:title "this is a new comment" .
+
+Because `/blog/entry1/` is a Basic Container the LDP Server will also automatically add a new triple to it. Issuing an `HTTP GET /blog/entry1/` now returns:
+
+    </blog/entry1/> a ldp:Container .
+    </blog/entry1/> dc:title "First blog entry" .
+    </blog/entry1/> ldp:contains </blog/entry1/comments1> .
+
+The important thing to notice is that by posting to a Basic Container, the LDP server automatically adds a triple with `ldp:contains` predicate pointing to the new resource created. 
+
+
+## Direct Container
+An Direct Container behaves a lot like a Basic Container but with some additional features. In a Direct Container we get to specify two additional attributes that the LDP Server will use to automatically add triples to *another resource* when posting new elements to the container. The *membershipResource* attribute will let the LDP Server know the URI of this other resource and the *hasMemberRelation* will indicate the predicate these new triples will have. 
+
+Assuming `/blog/entry1/` is a **Direct Container** created with *membershipResource* `/blog/comments` and *hasMemberRelation* `hasComment` 
+
+Issuing an `HTTP GET /blog/entry1/` returns
+
+    </blog/entry1/> a ldp:DirectContainer .
+    </blog/entry1/> ldp:membershipResource </blog/comments> .
+    </blog/entry1/> ldp:hasMemberRelation hasComment .
+    </blog/entry1/> dc:title "First blog entry" .
+
+Issuing an `HTTP POST /blog/entry1/` with `Slug: comment1` will result in 
+
+  1. A new resource created at `/blog/entry1/comment1`
+  2. A new triple (predicate `ldp:contains`) added to `/blog/entry1/`
+  3. A new triple (predicate `hasComment`) added to `/blog/comments`
+
+The first two items are identical to what we saw in the Basic Container example. Issuing an `HTTP GET /blog/entry1/comment1` will return the new resource created, something like this:
+
+    </blog/entry1/comment1/> a ldp:RDFSource .
+    </blog/entry1/comment1/> dc:title "this is a new comment" .
+
+Issuing an `HTTP GET /blog/entry1/` will show the new triple with `ldp:contains` predicate, just like in the Basic Container example:
+
+    </blog/entry1/> a ldp:DirectContainer .
+    </blog/entry1/> ldp:membershipResource </blog/comments> .
+    </blog/entry1/> ldp:hasMemberRelation hasComment .
+    </blog/entry1/> ldp:contains </blog/entry1/comments1> .
+
+The third item is what sets the Direct Container appart from the Basic Container. Issuing an `HTTP GET /blog/comments` will show also a new triple in this resource but this one with predicate `hasComment` as indicated by the `hasMembershipRelation` triple on the container: 
+
+    </blog/comments> hasComment </blog/entry1/comment1>
+
+Notice how a new triple was added to *a totally different resource*. In this case the triple was added to `/blog/comments` with predicate `hasComment` because that's what the *membershipResource* and *hasMemberRelationship* of the Direct Container specify.
+
+One thing to notice is that the resource added to `/blog/comments` will always be the URI of the newly created resource. In our example `/blog/comments` will get a new triple pointing to `/blog/entry1/comment1`. In other words, in a Direct Container we can configure the subject and the predicate of the new triple, but not the object. [Technically speaking this is not accurate, it is possible to revert the relationship by using is predicate *isMemberOfRelation* in the Direct Container instead of *hasMemberRelation* but for the sake of simplicity I am not going to dive into that scenario in this document.]
+
+
+## Indirect Container
+The Indirect Container is a bit like the Direct Container but with an extra twist. In an Indirect Container we can specify the subject, predicate, *and the object* of the new triple what will be added.
+
+Assumming `/blog/entry1/` is an **Indirect Container** created with *membershipResource* `/blog/comments`, *hasMemberRelation* `hasComment`, and *insertedContentRelation* `theComment`.
+
+Issuing an `HTTP GET /blog/entry1/` returns
+
+    </blog/entry1/> a ldp:IndirectContainer .
+    </blog/entry1/> ldp:membershipResource </blog/comments> .
+    </blog/entry1/> ldp:hasMemberRelation hasComment .
+    </blog/entry1/> ldp:insertedContentRelation theComment .
+    </blog/entry1/> dc:title "First blog entry" .
+
+When issuing an `HTTP POST` to an Indirect Container we need to specify some additional information for the LDP Server to be able to determine the *object* that will be used when adding the new triple to the `ldp:membershipResource`. In our particular example the body must contain an RDF triple with predicate `theComment`. For example, let's assume that we issue an `HTTP POST /blog/entry1/` with `Slug: comment1` and the following triple in the body of the POST request:
+
+    <> theComment </blog/extras/first/text> .
+
+The result of this HTTP will be 
+
+  1. A new resource created at `/blog/entry1/comment1`
+  2. A new triple (predicate `ldp:contains`) added to `/blog/entry1/`
+  3. A new triple (predicate `hasComment`, object `</blog/extras/first/text>`) added to `/blog/comments`
+
+The first two actions are identical to what we saw in Basic Container and Direct Container so I will not elaborate on them. 
+
+The third action is what is interesting in Indirect Containers. If we issue an `HTTP GET /blog/comments` we will see that a new triple has been added to it, and it will look as follows:
+
+    </blog/comments> hasComment </blog/extras/first/text>
+
+The subject of this triple (`/blog/comments`) and the predicate (`hasComment`) is what the *membershipResource* and the *hasMemberRelation* properties of the container indicated, similar to what we saw for Direct Containers. 
+
+However, the object of this new triple (`/blog/extras/first/text`) **is not the newly created `/blog/entry1/commment1` resource**. Instead, the object of this new triple is the object indicated in the triple with predicate `theComment` in the body of the request: `/blog/extras/first/text`. 
+
+When adding a new resource to an Indirect Container, the LDP Server looks at the body of the request for a triple with the same predicate as the *insertedContentRelation* property and picks from that triple the value to use as the object in the new triple.
+
+## LDP PDCM In Action
+Andrew Woods has posted a great tutorial that goes in more detail on how LDP containers can be used in a real life example. On [LDP-PCDM-F4 In Action](https://wiki.duraspace.org/display/FEDORA4x/LDP-PCDM-F4+In+Action) he shows how to represent the Portland Common Data Model (PCDM) using LDP in Fedora 4. His tutorial not only shows the differences between each of the containers but also provides cURL commands to create them in Fedora 4.
+
+Andrew's tutorial also addresses reversing the triples that are created in a Direct Container (by using `ldp:isMemberOfRelation` as opposed to `ldp:hasMemberRelation`) which is something that I explicitly skipped on this document.
+
+If you follow Andrew's tutorial with a plain-vanilla installation of Fedora 4 you might also find useful [Adam Wead scripts](https://github.com/awead/ldp-pcdm). However, if you are using an installation of Fedora via Hydra Jetty you will need to tweak the URLs provided by Andrew. You can find [here](https://github.com/hectorcorrea/ldp_pcdm_f4_in_action) the commands that I used to run his tutorial on a Fedora 4 installed via Hydra Jetty. 

data/doc/Lesson---Adding-attached-files.md

@@ -0,0 +1,83 @@
+# Goals
+* Attaching file sub-resources to models
+* See where files are stored in Fedora objects and how to retrieve them
+
+# Explanation
+
+So far, we've only added metadata to our objects.  Let's attach a file that has some content to it.  For example, for our Book model, this could be a image of the book's cover, or for the Page model, an image or pdf of the actual page.
+
+In this case, we'll add a file where we can store a pdf of a page.
+
+# Steps
+
+### Step 1: Add a "pageContent" file resource to the Page model
+
+In our Page model `app/models/page.rb`, we'll add the following line before the end of the class definition:
+
+```ruby
+contains "pageContent"
+```
+
+Now we have a resource called "pageContent" that can hold any kind of file we wish to add to it.  
+
+**NOTE:** The order of the property, relationship, and attachment (contains) statements within the class definition is not significant.  The edited version of  `app/models/page.rb` should look something like the version below, but the _title_, _number_, _belongs-to-book_, and _pageContent_ statements can come in any order.  We've jumbled things up for demonstration purposes - in real life, we'd probably have some convention that made the code easier to read.
+
+```ruby
+class Page < ActiveFedora::Base
+  contains "pageContent"
+  property :text, predicate: ::RDF::URI.new('http://opaquenamespace.org/hydra/pageText'), multiple: false do |index|
+    index.as :stored_searchable
+  end
+  belongs_to :book, predicate: ActiveFedora::RDF::Fcrepo::RelsExt.isPartOf
+  property :number, predicate: ::RDF::URI.new('http://opaquenamespace.org/hydra/pageNumber'), multiple: false do |index|
+    index.as :stored_searchable
+    index.type :integer
+  end
+end
+```
+
+### Step 2: In the console, add a file to a Page object and save it
+
+>*Note:* you can grab a copy of the sample file for this step by running `curl https://raw.githubusercontent.com/mark-dce/camper/master/sample-assets/AK-Page-4.pdf -o AK-Page-4.pdf` from the command line.
+
+To add the file to one of our page objects, open up the console again:
+
+```ruby
+ > p = Page.find("test-3")
+ => #<Page id: "test-3", number: 1, text: "Happy families are all alike; every unhappy family is unhappy in its own way.", book_id: "test-1"> 
+ > p.attached_files.keys
+ => [: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 assuming that you have a file named "AK-Page-4.pdf" in the parent directory where you started the tutorial.  Replace this with the correct local path for the file you want to use.
+
+```ruby
+ > p.pageContent.content = File.open("AK-Page-4.pdf")
+ => #<File:../AK-Page-4.pdf>
+ > p.pageContent.mime_type = "application/pdf"
+ => "application/pdf"
+ > p.pageContent.original_name = "AK-Page-4.pdf"
+ => "AK-Page-4.pdf"  
+ > p.save
+ => true
+ > p.pageContent.uri
+ => #<RDF::URI:0x3ff1d58f9bb4 URI:http://127.0.0.1:8984/rest/dev/test-3/pageContent>
+```
+
+### Step 3: See where the file was saved in Fedora
+
+Now if you go to [[http://127.0.0.1:8984/rest/dev/test-3]], you'll see the pageContent sub-resource  listed in the "children" section.
+
+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 file, it's a great time to commit to git:
+
+```bash
+git add .
+git commit -m "Created a content resource"
+```
+
+# Next Step
+Proceed to **BONUS** [[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-Codex-model-with-XML.md

@@ -0,0 +1,272 @@
+# Goals
+* Define a simple OM (Opinionated Metadata) Terminology for Codex Metadata that will be saved as an XML file attachment to our object (formerly known as a Datastream)
+* Start the Rails console and run code interactively in the console
+* Create Datastream objects that use your OM Terminology
+* Define an ActiveFedora Model for Codex objects 
+* Declare a Datastream called descMetadata on your Codex model and make it use your Codex Metadata Terminology
+* Delegate methods from Codex objects to their descMetadata Datastream
+* Create Codex objects that use your Codex Model
+* See how an object has been indexed into Solr
+* See how & where objects and metadata are stored in Fedora
+* Define how your Metadata is indexed in Solr
+* Re-index objects into Solr (update Solr based on any changes to an object or its Model)
+
+# Explanation
+In Fedora 4 an object can have many attachments.  Fedora 4 attachments work very similarly to Fedora 3 datastreams, but are generalized to support any type of binary attachment. In this lesson, we are going to create a 'codex' object.  This object will have metadata stored as an XML attachment that describes the properties of the codex.  We'll call this attachment '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 Codex 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/codex_metadata.rb`
+
+Paste the following code into that file:
+
+```ruby
+class CodexMetadata < 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
+```
+
+(Or you can abbreviate this as ```rails c```.)
+
+You should see something like `Loading development environment (Rails 4.2.0)`.  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 CodexMetadata instance. I've shown the expected output after each command:
+
+```text
+d = CodexMetadata.new
+ => #<CodexMetadata uri="" >
+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" 
+puts d.to_xml
+<?xml version="1.0"?>
+<fields>
+  <title>ZOIA! Memoirs of Zoia Horn, Battler for the People's Right to Know.</title>
+  <author>Horn, Zoia</author>
+</fields>
+ => nil 
+```
+
+Once you're done, exit the console by typing ```exit```
+
+
+### Step 4: Define a Codex Object Model
+
+Now let's create a model that uses this datastream.  Create a new file at `app/models/codex.rb`. We'll paste in this code:
+
+```ruby
+class Codex < ActiveFedora::Base
+  contains 'descMetadata', class_name: 'CodexMetadata'
+
+  property :title, delegate_to: 'descMetadata', multiple: false
+  property :author, delegate_to: 'descMetadata', multiple: false
+
+end
+```
+
+We've instructed our Codex model to use the CodexMetadata class to interpret XML metadata stored in a file attachment 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, add metadata terms to your object using your OM Terminology.
+
+Now we'll open the `rails console` again and see how to work with our codex.
+
+```text
+c = Codex.create(id: 'test-2', title: 'On the Equilibrium of Planes', author: 'Archimedes of Syracuse')
+ => #<Codex id: "test-2", title: "On the Equilibrium of Planes", author: "Archimedes of Syracuse"> 
+```
+
+We've created a new Codex object in the repository. 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
+c.descMetadata
+ => #<CodexMetadata uri="http://127.0.0.1:8984/rest/dev/test-1/descMetadata" > 
+c.title
+ => "On the Equilibrium of Planes" 
+c.author
+ => "Archimedes of Syracuse"
+c.descMetadata.title
+ => ["On the Equilibrium of Planes"] 
+c.descMetadata.author
+ => ["Archimedes of Syracuse"] 
+```
+
+Note, because we used the `.create` method the new object was automatically saved to fedora.  In general, you either need to use the `.new` method followed at some point by the `.save` OR the `.create` method to both build and save a new object.  Any time you make changes to an object, you need to call `.save` on the object to make your changes persistent.  
+
+### Step 6: See what your Codex objects look like in Fedora and Solr
+
+If we go to [[http://localhost:8984/rest/dev/test-2]] we should see what it looks like in fedora.  If you followed the example and used test-2 for your codex's ID, the solr page will be [[http://localhost:8983/solr/hydra-development/select?q=test-2]] - the generic pattern looks like this: http://localhost:8983/solr/hydra-development/select?q=XXX and replace the XXX with the id from your console session. The page should look like the sample below. Note that, at this point, the `title` and `author` have not been indexed 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 codex model to add the codex metadata to the solr document.
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<response>
+  <lst name="responseHeader">
+    <int name="status">0</int>
+    <int name="QTime">2</int>
+    <lst name="params">
+      <str name="q">test-2</str>
+    </lst>
+  </lst>
+  <result name="response" numFound="1" start="0" maxScore="0.029457245">
+    <doc>
+      <date name="system_create_dtsi">2015-03-28T03:11:45Z</date>
+      <date name="system_modified_dtsi">2015-03-28T03:11:45Z</date>
+      <str name="active_fedora_model_ssi">Codex</str>
+      <arr name="has_model_ssim">
+        <str>Codex</str>
+      </arr>
+      <str name="id">test-2</str>
+      <arr name="object_profile_ssm">
+        <str>{"id":"test-2","title":"On the Equilibrium of Planes","author":"Archimedes of Syracuse"}</str>
+      </arr>
+      <long name="_version_">1496855143638892544</long>
+      <date name="timestamp">2015-03-28T03:11:45.868Z</date>
+      <float name="score">0.029457245</float>
+    </doc>
+  </result>
+  <lst name="facet_counts">
+    <lst name="facet_queries"/>
+    <lst name="facet_fields">
+      <lst name="active_fedora_model_ssi">
+        <int name="Codex">1</int>
+      </lst>
+      <lst name="object_type_si"/>
+    </lst>
+    <lst name="facet_dates"/>
+    <lst name="facet_ranges"/>
+    <lst name="facet_intervals"/>
+  </lst>
+  <lst name="spellcheck">
+    <lst name="suggestions">
+      <bool name="correctlySpelled">true</bool>
+    </lst>
+  </lst>
+</response>
+```
+
+If you completed the RDF modeling lesson, you can see that other than the object model name, the Solr output looks identical regardless of whether we use XML or RDF to store our metadata.  In the next step we will modify our CodexMetadata datastream to add the codex metadata to the solr document.
+
+### Step 7: See how your Codex metadata are indexed into Solr
+
+
+The to_solr method is what generates the solr document for your objects and their datastreams. The solr document represents the terms that will be indexed in solr for each object. To see the full solr document for the codex we created, call
+
+```text
+c.to_solr
+ => {"system_create_dtsi"=>"2015-03-28T03:11:45Z", "system_modified_dtsi"=>"2015-03-28T03:11:45Z", "active_fedora_model_ssi"=>"Codex", "has_model_ssim"=>["Codex"], :id=>"test-2", "object_profile_ssm"=>"{\"id\":\"test-2\",\"title\":\"On the Equilibrium of Planes\",\"author\":\"Archimedes of Syracuse\"}"} 
+```
+
+As you can see, the author and title values are included in the object profile, but they aren't being indexed as individual terms.
+
+### Step 8: Change how your Codex metadata are indexed into Solr
+
+To make your codex object the author and title fields, you need to reopen `app/models/codex.rb` and specify which terms you would like indexed and how:
+
+```ruby
+class Codex < ActiveFedora::Base
+  contains 'descMetadata', class_name: 'CodexMetadata'
+
+  property :title, delegate_to: 'descMetadata', multiple: false  do |index|
+    index.as :stored_searchable
+  end
+  property :author, delegate_to: 'descMetadata', multiple: false do |index|
+    index.as :stored_searchable
+  end
+
+end
+```
+
+**Note:** Because we have made changes to our Ruby code that we want to use, we need to reload all of the code, including our latest changes.  There are two methods to do this:
+* Exit and restart the rails console: `exit` the rails console followed by `rails c` from the shell prompt
+* Reload the application code by calling `reload!` from within the rails console itself.
+
+So, **restart the rails console** using either method and we can load the object we previously created:
+
+```text
+c = Codex.find('test-2')
+ => #<Codex id: "test-2", title: "On the Equilibrium of Planes", author: "Archimedes of Syracuse">
+```
+
+Check and see that to_solr includes the title and author fields.
+
+```text
+c.to_solr
+ => {"system_create_dtsi"=>"2015-03-28T03:11:45Z", "system_modified_dtsi"=>"2015-03-28T03:11:45Z", "active_fedora_model_ssi"=>"Codex", "has_model_ssim"=>["Codex"], :id=>"test-2", "object_profile_ssm"=>"{\"id\":\"test-2\",\"title\":\"On the Equilibrium of Planes\",\"author\":\"Archimedes of Syracuse\"}", "title_tesim"=>["On the Equilibrium of Planes"], "author_tesim"=>["Archimedes of Syracuse"]} 
+```
+Now when you call `.to_solr` on a codex 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
+c.update_index
+ => {"responseHeader"=>{"status"=>0, "QTime"=>44}}
+```
+
+If you refresh the document result from solr ([[http://localhost:8983/solr/hydra-development/select?q=test-2]]) you should see that these fields have been added to the solr_document:
+
+```xml
+<arr name="title_tesim">
+  <str>On the Equilibrium of Planes</str>
+</arr>
+<arr name="author_tesim">
+  <str>Archimedes of Syracuse</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](https://github.com/projecthydra/hydra-head/wiki/Solr-Schema). 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 **still 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 lesson.
+
+### Step 10: Commit your changes
+
+Now that we've got our model working, it's a great time to commit to git:
+
+```text
+git add .
+git commit -m "Create a codex model and a datastream"
+```
+
+# Next Step
+Go on to [[Lesson - Make Blacklight Return Search Results]] 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.