hydra-tutorial 0.0.1

data/templates/application/mods_desc_metadata.rb

@@ -0,0 +1,135 @@
+class ModsDescMetadata < ActiveFedora::NokogiriDatastream
+  # MODS XML constants.
+
+  MODS_NS = 'http://www.loc.gov/mods/v3'
+  MODS_SCHEMA = 'http://www.loc.gov/standards/mods/v3/mods-3-3.xsd'
+  MODS_PARAMS = {
+    "version"            => "3.3",
+    "xmlns:xlink"        => "http://www.w3.org/1999/xlink",
+    "xmlns:xsi"          => "http://www.w3.org/2001/XMLSchema-instance",
+    "xmlns"              => MODS_NS,
+    "xsi:schemaLocation" => "#{MODS_NS} #{MODS_SCHEMA}",
+  }
+
+  # OM terminology.
+
+  set_terminology do |t|
+    t.root :path => 'mods', :xmlns => MODS_NS
+    t.originInfo  do
+      t.dateOther
+    end
+    t.abstract
+    t.titleInfo  do
+      t.title
+    end
+
+    t.title :ref => [:mods, :titleInfo, :title]
+    t.name  do
+      t.namePart
+      t.role  do
+        t.roleTerm
+      end
+    end
+
+    t.relatedItem  do
+      t.titleInfo  do
+        t.title
+      end
+      t.location  do
+        t.url
+      end
+    end
+
+    t.subject  do
+      t.topic
+    end
+
+    t.preferred_citation :path => 'note',  :attributes => { :type => "preferred citation" }
+    t.related_citation :path => 'note',  :attributes => { :type => "citation/reference" }
+
+  end
+
+  # Blocks to pass into Nokogiri::XML::Builder.new()
+
+  define_template :name do |xml|
+      xml.name {
+        xml.namePart
+        xml.role {
+          xml.roleTerm(:authority => "marcrelator", :type => "text")
+        }
+      }
+  end
+
+  define_template :relatedItem do |xml|
+      xml.relatedItem {
+        xml.titleInfo {
+          xml.title
+        }
+        xml.location {
+          xml.url
+        }
+      }
+  end
+
+  define_template :related_citation do |xml|
+    xml.note(:type => "citation/reference")
+  end
+
+  def self.xml_template
+    Nokogiri::XML::Builder.new do |xml|
+      xml.mods(MODS_PARAMS) {
+        xml.originInfo {
+          xml.dateOther
+        }
+        xml.abstract
+        xml.titleInfo {
+          xml.title
+        }
+        xml.name {
+          xml.namePart
+          xml.role {
+            xml.roleTerm
+          }
+        }
+        xml.relatedItem {
+          xml.titleInfo {
+            xml.title
+          }
+          xml.location {
+            xml.url
+          }
+        }
+        xml.subject {
+          xml.topic
+        }
+        xml.note(:type => "preferred citation")
+        xml.note(:type => "citation/reference")
+      }
+    end.doc
+  end
+
+  def insert_person
+    insert_new_node(:name)
+  end
+
+  def insert_related_item
+    insert_new_node(:relatedItem)
+  end
+
+  def insert_related_citation
+    insert_new_node(:related_citation)
+  end
+
+  def insert_new_node(term)
+    add_child_node(ng_xml.root, term)
+  end
+
+  def remove_node(term, index)
+    node = self.find_by_terms(term.to_sym => index.to_i).first
+    unless node.nil?
+      node.remove
+      self.dirty = true
+    end
+  end
+
+end

data/templates/building_a_basic_rails_app/dataset_af_om.rb

@@ -0,0 +1,34 @@
+class Dataset < ActiveFedora::Base
+
+  class DatastreamMetadata < ActiveFedora::NokogiriDatastream
+
+    ##
+    # Here's the important part. We're mapping XML into Ruby.
+    set_terminology do |t|
+      t.root :path => 'root', :xmlns => nil
+      t.title
+      t.author
+      t.url
+      t.description
+    end
+
+    def self.xml_template
+      Nokogiri::XML::Builder.new do |xml|
+        xml.root do
+          xml.title
+          xml.author
+          xml.url
+          xml.description
+        end
+      end.doc
+    end
+  end
+
+  has_metadata :name => "descMetadata", :type => DatastreamMetadata
+
+  delegate :title, :to=>'descMetadata', :unique=>true
+  delegate :author, :to=>'descMetadata', :unique=>true
+  delegate :url, :to=>'descMetadata', :unique=>true
+  delegate :description, :to=>'descMetadata', :unique=>true
+
+end

data/templates/building_a_basic_rails_app/dataset_simple_om.rb

@@ -0,0 +1,24 @@
+class Dataset < OmRecord # OmRecord contains code that lets us pretend this Dataset is a drop-in replacement for the ActiveRecord.
+  include OM::XML::Document
+
+  ##
+  # Here's the important part. We're mapping XML into Ruby.
+  set_terminology do |t|
+    t.root :path => 'root', :xmlns => nil
+    t.title
+    t.author
+    t.url
+    t.description
+  end
+
+  def self.xml_template
+    Nokogiri::XML::Builder.new do |xml|
+      xml.root do
+        xml.title
+        xml.author
+        xml.url
+        xml.description
+      end
+    end.doc
+  end
+end

data/templates/building_a_basic_rails_app/fedora.yml

@@ -0,0 +1,14 @@
+development:
+  user: fedoraAdmin
+  password: fedoraAdmin
+  url: http://127.0.0.1:8983/fedora
+test: &TEST  
+  user: fedoraAdmin
+  password: fedoraAdmin
+  url: <%= "http://127.0.0.1:#{ENV['TEST_JETTY_PORT'] || 8983}/fedora-test" %>
+production:
+  user: fedoraAdmin
+  password: fedoraAdmin
+  url: http://your.production.server:8080/fedora
+cucumber:
+  <<: *TEST

data/templates/building_a_basic_rails_app/om_record.rb

@@ -0,0 +1,63 @@
+class OmRecord 
+  extend ActiveSupport::Concern
+
+  included do
+    ##
+    # This stuff is so we can store and retrieve data off the filesystem. Don't worry about it.
+    extend ActiveModel::Naming
+    include ActiveModel::Conversion
+
+    attr_writer :file
+  
+    attr_accessor :name
+    attr_reader   :errors
+  end
+
+  def initialize options={}
+
+    @errors = ActiveModel::Errors.new(self)
+
+    self.ng_xml = self.class.xml_template
+
+    options.each do |k,v|
+      send("#{k}=", v)
+    end
+  end
+
+  def file
+    @file ||= "db/datasets/#{Time.now.to_i}"
+  end
+
+  def id
+    File.basename(file)
+  end
+
+  def save
+    File.open(file, 'w') { |f| f.puts ng_xml.to_s }
+  end
+
+  def persisted?
+    File.exists? file
+  end
+
+  class ClassMethods
+    def all
+      Dir.glob('db/datasets/*').map do |f|
+        Dataset.from_file(f)
+      end
+    end
+
+    def find id
+      Dataset.from_file("db/datasets/#{id}")
+    end
+
+    def from_file f
+      d = Dataset.from_xml(File.read(f))
+
+      d.file = f
+
+      d
+    end
+  end
+end
+

data/templates/building_a_basic_rails_app/solr.yml

@@ -0,0 +1,10 @@
+# This is a sample config file that does not have multiple solr instances. You will also need to be sure to
+# edit the fedora.yml file to match the solr URL for active-fedora. 
+development:
+  url: http://localhost:8983/solr/development
+test: &TEST
+  url: <%= "http://127.0.0.1:#{ENV['TEST_JETTY_PORT'] || 8983}/solr/test" %>
+cucumber:
+  <<: *TEST
+production:
+  url: http://your.production.server:8080/bl_solr/core0 

data/tutorial.thor

@@ -0,0 +1,493 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'thor'
+require 'thor/group'
+require 'rails/generators/actions'
+require 'active_support/core_ext/array/extract_options'
+
+$base_templates_path = File.expand_path(File.join(File.dirname(__FILE__), 'templates'))
+
+class HydraTutorialApp < Thor::Group
+  class_option :quick, :default => false
+
+  def welcome
+    $quick = options[:quick]
+    say %Q{
+    Welcome to this Hydra tutorial. We're going to go through some steps to
+    set up a working Hydra head. We'll build the application gradually, and give you
+    opportunities to stop and look around on the way.
+    }, Thor::Shell::Color::YELLOW
+
+    if $quick
+      say %Q{
+    We'll quickly build the application, give you some Hydra models, and send you on your way.
+      }, Thor::Shell::Color::YELLOW
+
+    else
+      say %Q{
+    We'll go through this tour slowly, starting by creating a pure Rails application, 
+    and then introduce Hydra components. If you want to speed things along, 
+      }, Thor::Shell::Color::YELLOW
+
+     exit unless yes? %Q{
+    If you want to speed things along, you should quit this tutorial (by saying 'no'), 
+    and run it again with ./tutorial.thor --quick=yes. 
+
+    Do you want to continue at this pace? (y/n) }, Thor::Shell::Color::GREEN
+    end
+  end
+
+  include Thor::Actions
+  include Rails::Generators::Actions
+
+  class Prerequisites < Thor::Group
+    class_option :quick, :default => false
+    include Thor::Actions
+    include Rails::Generators::Actions
+
+    def install_ruby
+      return if $quick
+      say %Q{ 
+    Obviously, if you can run this tutorial, you have already installed ruby.
+      }, Thor::Shell::Color::YELLOW
+
+
+      ruby_executable = run 'which ruby', :capture => true
+
+      say %Q{
+    You are running this using:
+    #{ruby_executable}
+      }, Thor::Shell::Color::YELLOW
+
+      if ruby_executable =~ /rvm/ or ruby_executable =~ /rbenv/ or ruby_executable =~ /home/ or ruby_Executable =~ /Users/
+        say %Q{
+    It looks like you're using rvm/rbenv/etc. (with a gemset?) We'll use this environment to build the application.
+      }, Thor::Shell::Color::YELLOW
+
+      else
+
+      say %Q{
+    We checked, and it looks like you might be using a system-wide ruby. We'd like to
+    suggest you use somethng like rvm [1], rbenv [2], etc to manage your ruby projects.
+
+    [1] http://rvm.io/
+    [2] https://github.com/sstephenson/rbenv/
+      }, Thor::Shell::Color::RED
+
+      exit unless yes? %Q{
+    You can continue and hope for the best, or go install one of these ruby managers, which may make your life easier.
+
+    Do you want to continue anyway? (y/n)
+      }, Thor::Shell::Color::GREEN
+      end
+
+    end
+
+    def install_bundler_and_rails
+      say %Q{
+    We're going to install some prerequisite gems in order to create our skeleton Rails application.
+      }, Thor::Shell::Color::YELLOW
+      run 'gem install bundler rails'
+    end
+
+    def new_rails_app
+      say %Q{
+    Now we'll create the application.
+      }, Thor::Shell::Color::YELLOW
+      run 'rails new hydra_tutorial_app'
+      run 'cd hydra_tutorial_app'
+
+    end
+
+    def out_of_the_box
+      return if $quick
+      say %Q{ 
+    Here's a chance to look around. You can see the structure of a Rails application.
+       ./app
+       ./config
+       ./lib
+       Gemfile
+      }
+
+      ask %Q{
+
+    Hit ENTER when you're ready to continue.
+      }, Thor::Shell::Color::GREEN
+    end
+
+    # and then clean up some cruft
+    def remove_public_index
+      say %Q{
+    We'll now remove the Rails directions from the application.
+      }, Thor::Shell::Color::YELLOW
+      inside 'hydra_tutorial_app' do
+        remove_file 'public/index.html'
+      end
+    end
+  end
+
+  class BuildingABasicRailsApp < Thor::Group
+    include Thor::Actions
+    include Rails::Generators::Actions
+
+    def self.source_paths
+      [File.join($base_templates_path, "building_a_basic_rails_app")]
+    end
+
+    def notes
+      say %Q{
+    We're going to build an application to track (simplified) datasets and their metadata.
+      }, Thor::Shell::Color::YELLOW
+    end
+
+    def as_if_this_was_just_a_rails_applications
+      say %Q{
+    If we wanted to build a Rails application to do this, we would add some models and controllers.
+
+    Rails can help "scaffold" the application for us.
+      }, Thor::Shell::Color::YELLOW
+
+      generate 'scaffold', 'dataset', 'title', 'author', 'url', 'description:text'
+      rake 'db:migrate'
+
+      say %Q{
+    This created a Dataset model (in ./app/models/dataset.rb), a controller, and some views.
+      }, Thor::Shell::Color::YELLOW
+
+      ask %Q{
+    Take a look around. Hit ENTER when you're ready to continue.
+      }, Thor::Shell::Color::GREEN
+    end
+
+    def but_maybe_we_want_to_store_our_metadata_as_xml
+      say %Q{
+    But it turns out a relational database is not a great place to store complex metadata objects, 
+    with nesting, hierarchy, repetition, etc like we often fine in the digital library world. We'd 
+    also like to store and manage our data in an exchangeable form rather than a custom-built database.
+
+    In our world, we often find ourselves dealing with XML-based metadata. Fortunately, we have a gem called 'om' that can help us deal with XML metadata.
+    To start using it, we need to add it to our Gemfile.
+      }, Thor::Shell::Color::YELLOW
+
+      gem 'om'
+      run 'bundle install'
+
+      say %Q{
+    Now let's adapt our Dataset model to use OM. First we'll add some code that allows us to persist our
+    OM Documents on the filesystem (in db/datasets) and then add a simple OM terminology as a drop-in
+    replacement for the ActiveRecord scaffold object.
+
+      }, Thor::Shell::Color::YELLOW
+
+      run "mkdir db/datasets"
+      copy_file "om_record.rb", "app/models/om_record.rb"
+
+      say %Q{
+    Press 'd' to see the difference between the Rails version and the OM version of Dataset.
+      }, Thor::Shell::Color::YELLOW
+
+      copy_file "dataset_simple_om.rb", "app/models/dataset.rb"
+
+      ask %Q{ 
+    Take a look around. 
+
+    Hit ENTER when you're ready to continue.
+      }, Thor::Shell::Color::GREEN
+
+    end
+
+
+    def stop_using_the_filesystem
+      say %Q{
+    Storing the documents on the filesystem has worked so far, but what if we wanted to start
+    managing whole objects (instead of XML documents), version datastream, keep checksums...
+
+    We use Fedora [3], and ActiveFedora to work with data in our repository. We also use Solr to
+    index and provide searching, faceting, etc for our content. For now, you can just concentrate on
+    Fedora. We'll have a section on Solr and discovery interfaces later.
+
+    [3] http://fedora-commons.org 
+      }, Thor::Shell::Color::YELLOW
+
+      say %Q{
+    Fedora runs as a java servlet inside a container like Tomcat or Jetty. Hydra provides a bundled
+    version of Fedora and Solr for testing and development.
+      }, Thor::Shell::Color::YELLOW
+
+      say %Q{
+    We'll download a copy now. It may take awhile.
+      }, Thor::Shell::Color::YELLOW
+      unless File.exists? '../jetty'
+        git :clone => 'git://github.com/projecthydra/hydra-jetty.git ../jetty'
+      end
+      run 'cp -R ../jetty jetty'
+#      run 'rake hydra:jetty:config'
+
+      say %Q{ 
+    Now we're configure it and start the application.
+      }, Thor::Shell::Color::YELLOW
+      rake 'hydra:jetty:config'
+
+      copy_file 'solr.yml', 'config/solr.yml'
+      copy_file 'fedora.yml', 'config/fedora.yml'
+
+      say %Q{
+    And we'll use jettywrapper to help start and stop the service.
+      }, Thor::Shell::Color::YELLOW
+
+      gem 'jettywrapper'
+      run 'bundle install'
+      rake 'jetty:start'
+
+      say %Q{ 
+    Take a look around. Jetty should be running on port 8983. You can see the Fedora server at
+
+      http://localhost:8983/fedora/
+
+    And a Solr index at
+
+      http://localhost:8983/solr/development/admin/
+      }, Thor::Shell::Color::YELLOW
+
+      ask %Q{
+    Hit ENTER when you're ready to continue.
+      }, Thor::Shell::Color::GREEN
+
+    end
+
+    def convert_our_model_to_activefedora
+      say %Q{
+    We'll update our Dataset object to use ActiveFedora.
+      }, Thor::Shell::Color::YELLOW
+
+      gem 'active-fedora'
+      run 'bundle install'
+      copy_file "dataset_af_om.rb", "app/models/dataset.rb"
+
+      say %Q{
+    You should be able to create new dataset objects and see them updated in Fedora.
+      }, Thor::Shell::Color::YELLOW
+
+      ask %Q{
+    Hit ENTER when you're ready to continue.
+      }, Thor::Shell::Color::GREEN
+    end
+  end
+
+  class Application < Thor::Group
+    include Thor::Actions
+    include Rails::Generators::Actions
+
+    def self.source_paths
+      [File.join($base_templates_path, "application")]
+    end
+
+    # here are some gems that help
+    def add_blacklight_and_hydra
+      say %Q{
+    Eventually, common patterns get packaged up into new gems.
+      }, Thor::Shell::Color::YELLOW
+
+      say %Q{ 
+    We use blacklight to provide a search interface.
+      }, Thor::Shell::Color::YELLOW
+
+      gem 'blacklight'
+      run 'bundle install'
+      generate 'blacklight', '--devise'
+
+      say %Q{
+    And hydra-head bundles OM, ActiveFedora, etc for us. It also includes things like
+    gated discovery and permissions (through hydra-access-controls).
+      }, Thor::Shell::Color::YELLOW
+
+      gem 'hydra-head', "~> 4.1"
+      run 'bundle install'
+      generate 'hydra:head', 'User'
+    end
+
+    def rake_db_migrate
+      rake 'db:migrate'
+      rake 'db:test:prepare'
+    end
+
+    def install_hydra_jetty
+      if $quick # if we were in quick mode, we skipped this step from before.. 
+        say %Q{
+    Fedora runs as a java servlet inside a container like Tomcat or Jetty. Hydra provides a bundled
+    version of Fedora and Solr for testing and development.
+        }, Thor::Shell::Color::YELLOW
+
+        say %Q{
+    We'll download a copy now. It may take awhile.
+        }, Thor::Shell::Color::YELLOW
+
+        unless File.exists? '../jetty'
+          git :clone => 'git://github.com/projecthydra/hydra-jetty.git ../jetty'
+        end
+        run 'cp -R ../jetty jetty'
+
+        rake 'hydra:jetty:config'
+
+        gem 'jettywrapper'
+        run 'bundle install'
+        rake 'jetty:start'
+      else
+
+        rake 'jetty:stop'
+        rake 'hydra:jetty:config'
+        rake 'jetty:start'
+      end
+
+    end
+
+    def fixup_ui
+      remove_file 'app/assets/stylesheets/datasets.css.scss'
+      remove_file 'app/assets/stylesheets/scaffolds.css.scss'
+    end
+
+    def fixup_datasets
+      return if $quick
+      say %Q{
+    We need to make a couple of tweaks to our Dataset model and controller in order
+    to make it a Hydra-compliant object.
+
+    Because Hydra enforces access controls in the discovery layer (and, by default, no one
+    has access), we need to teach our model and controller about the Hydra rightsMetadata model
+    and have the controller tell the object who deposited it.
+      }, Thor::Shell::Color::YELLOW
+
+      copy_file "dataset_hydra_om.rb", "app/models/dataset.rb"
+
+      inject_into_class "app/controllers/datasets_controller.rb", 'DatasetsController' do
+        "  include Hydra::AssetsControllerHelper\n"
+      end
+
+      insert_into_file "app/controllers/datasets_controller.rb", :after => "@dataset = Dataset.new(params[:dataset])\n" do
+        "    apply_depositor_metadata(@dataset)\n"
+      end
+    end
+
+    def lets_make_a_better_terminology
+      say %Q{
+    So far, we've been working with a made-up XML schema, however, in the real world, we're probably
+    dealing with more complex data in well-known standards like MODS.
+
+    Now we'll replace our custom schema with a basic MODS schema.
+      }, Thor::Shell::Color::YELLOW
+      copy_file "mods_desc_metadata.rb", "app/models/mods_desc_metadata.rb"
+      copy_file "dataset_hydra_mods_om.rb", "app/models/dataset.rb"
+    end
+
+  end
+
+  class MakeItNice < Thor::Group
+    include Thor::Actions
+    include Rails::Generators::Actions
+
+    def self.source_paths
+      [File.join($base_templates_path, "make_it_nice")]
+    end
+
+    # now we want our app to do stuff.. so lets enhance our old models
+
+    def some_better_views
+
+    end
+
+    def file_uploads
+
+    end
+
+
+    def sprinkle_some_css
+
+    end
+
+  end
+
+  class Tests < Thor::Group
+    include Thor::Actions
+    include Rails::Generators::Actions
+
+    # and write some tests
+
+  end
+
+  class InitialSteps < Thor::Group
+    include Thor::Actions
+    include Rails::Generators::Actions
+
+    # here are some steps you can do to get started
+    def create_a_user_account
+
+    end
+
+    def explore_the_application
+      run 'rails s'
+
+    end
+  end
+
+  
+  class Cleanup < Thor::Group
+    include Thor::Actions
+    include Rails::Generators::Actions
+
+    # and write some tests
+    #
+    def stop_jetty
+      rake 'jetty:stop'
+    end
+
+  end
+
+  def prerequisites
+    Prerequisites.start
+  end
+
+  def building_a_basic_rails_app
+    return if $quick
+
+    inside 'hydra_tutorial_app' do
+      BuildingABasicRailsApp.start
+    end
+  end
+  
+  def application
+    inside 'hydra_tutorial_app' do
+      Application.start
+    end
+  end
+
+  def make_it_nice
+    return if $quick
+    inside 'hydra_tutorial_app' do
+      MakeItNice.start
+    end 
+  end
+
+  def tests
+    inside 'hydra_tutorial_app' do
+      Tests.start
+    end
+  end
+
+  def initial_steps
+    return if $quick
+    inside 'hydra_tutorial_app' do
+      InitialSteps.start
+    end
+  end
+
+  def cleanup
+    yes? "All Done?", Thor::Shell::Color::GREEN
+    inside 'hydra_tutorial_app' do
+      Cleanup.start
+    end
+  end
+
+end
+
+HydraTutorialApp.start