h1. Using OM-based NokogiriDatastreams

h2. Setup

This tutorial assumes that you've run script/console from the root of ActiveFedora and have imported the hydrangea:fixture_mods_article1 object.  If you haven't done that, see "CONSOLE_GETTING_STARTED":https://github.com/mediashelf/active_fedora/blob/master/CONSOLE_GETTING_STARTED.textile for instructions.

The model definition we're using in this tutorial is {SpecialThing} ( "see the code":https://github.com/mediashelf/active_fedora/blob/master/lib/active_fedora/samples/special_thing.rb )


Look in these datastream definitions to see the OM Terminologies they define.  They have extra comments in the code:
* {Hydra::ModsArticleDatastream} ( "see the code":https://github.com/mediashelf/active_fedora/blob/master/lib/active_fedora/samples/hydra-mods_article_datastream.rb ) 
* {Hydra::RightsMetadataDatastream} ( "see the code":https://github.com/mediashelf/active_fedora/blob/master/lib/active_fedora/samples/hydra-rights_metadata_datastream.rb }
* {Marpa::DcDatastream} ( "see the code":https://github.com/mediashelf/active_fedora/blob/master/lib/active_fedora/samples/marpa-dc_datastream.rb )


h2. The First Pass with OM

First, load the Fedora object as an instance of the SpecialThing Model

<pre>
st = SpecialThing.load_instance("hydrangea:fixture_mods_article1")
</pre>

Take a look at the datastreams in the object.

<pre>
st.datastreams.keys
</pre>

Each datastream is associated with a class that is aware of its content.  These classes are specified in the model.  

<pre>
st.datastreams["rightsMetadata"].class
st.datastreams["descMetadata"].class
</pre>
  
You can retrieve the xml from the object as xml (string) using to_xml, or you can access it as a Nokogiri::XML::Document using .ng_xml

<pre>
st.datastreams["rightsMetadata"].to_xml
st.datastreams["rightsMetadata"].ng_xml.class
</pre>

An OM terminology is attached to the datastream's class.  OM's convenience methods use the terminology to look up nodes and values for you.

<pre>
st.datastreams["rightsMetadata"].class.terminology
Hydra::RightsMetadataDatastream.terminology
</pre>

The Terminology in Hydra::ModsArticleDatastream lets you retrieve values from the descMetadata datastream's MODS content.

<pre>
mods_ds = st.datastreams["descMetadata"]
mods_ds.term_values(:person, :first_name)
mods_ds.term_values(:person, :last_name)
</pre>

You can use OM's find_by_terms method to retrieve xml nodes from the datastream.  It returns Nokogiri::XML::Node objects.

<pre>
mods_ds.find_by_terms(:person)
mods_ds.find_by_terms(:person).length
mods_ds.find_by_terms(:person).each {|n| puts n.to_xml}
</pre>


h2. Learning More about OM

Hydra::ModsArticleDatastream has all of the behaviors of an OM::Document.  For deeper exposure to what you can do with OM, see the "OM documentation":http://hudson.projecthydra.org/job/om/Documentation/ for "Getting Started":http://hudson.projecthydra.org/job/om/Documentation/file.GETTING_STARTED.html, "Querying Documents":http://hudson.projecthydra.org/job/om/Documentation/file.QUERYING_DOCUMENTS.html, and "Updating Documents":http://hudson.projecthydra.org/job/om/Documentation/file.UPDATING_DOCUMENTS.html.   There is also information in the "solrizer":http://github.com/projecthydra/solrizer documentation about Solrizing documents. 

You can run most of the examples from those tutorials against the descMetadata datastream you've created here.

<pre>
doc = st.datastreams["descMetadata"]  # the datastream is the OM Document
...
doc.class
=> Hydra::ModsArticleDatastream  # Hydra::ModsArticleDatastream is the Document Class
terminology = doc.class.terminology # The terminology is attached to the Document Class
</pre>


h1. Setting the XML in a NokogiriDatastream from a file

h2. Creating a new Datastream using from_xml

<pre>
my_path = "spec/fixtures/mods_articles/hydrangea_article1.xml"
f = File.new(my_path)
mods_ds = Hydra::ModsArticleDatastream.from_xml(f)
</pre>

If you want to add that datastream to an object, set the datastream's dsid and then pass the datastream into the object's add_datastream method.

<pre>
mods_ds.dsid = "descMetadata"
st.add_datastream(mods_ds)
</pre>


h2. Saving the Datastream

After calling add_datastream, then everything will be ready to save to Fedora.  In order to make sure that your updated datastream is actually saved to fedora, call .save _on the datastream_.  If you call .save on the _object_, the changes you've made to the datastream might not be saved.

<pre>
st.datastreams["descMetadata"].save
</pre>