atrium 0.0.1.alpha → 0.0.1

data/GETTING_STARTED.textile

@@ -1,74 +1,72 @@
-h1. Getting Started using atrium in your own Application
+h1. Atrium
+
+Atrium is a Ruby-on-Rails 3 gem containing the core code for a web application to build collection based of blacklight which build faceted search and discovery layer on top of solr
 
 h2. Before You Begin
 
 *!!! This is a WORK IN PROGRESS !!!*
 
-This tutorial is a work in progress.
-
-h1. Atrium
-
-Atrium is a Rails Engines plugin containing the core code for a Atrium application.  The full hydra stack includes the following:
+h2. Installation/Setup
 
-- "Blacklight":http://projectblacklight.org/  (a rails engines plugin) for the User Interface
-- "Solr":http://lucene.apache.org/solr/ (a java application, also ported to other languages) for the Search Engine
-- Atrium (a rails engines plugin) to create collection, exhibit and showcase base on the blacklight configuration
+h3. Installation Prerequisites
 
 
-This is a Ruby on Rails 3 gem.
+Ruby 1.8.7 is required by Atrium release 4.0; RVM is strongly suggested.
 
-h2. Installation/Setup
+h3. Install Rails
 
-h3. Install Rails, Bundler and Devise
-
-Currently Atrium is compatible with Rails 3.1
+Currently Atrium is compatible with Rails 3.2
 
 <pre>
-gem install 'rails' --version '~>3.0.11'
-gem install 'bundler'
+gem install 'rails' --version '~>3.2.2'
 </pre>
 
 h3. Generate a new rails application:
 
 <pre>
-rails new my_hydra_head
-cd my_hydra_head
+rails new my_atrium_app
+cd my_atrium_app
 </pre>
 
 h3. Install Dependencies
 
-First, add them to the "Gemfile":http://gembundler.com/gemfile.html of your application:
+First, add them to the "Gemfile":http://gembundler.com/gemfile.html of your application.  You may already have a Gemfile in the new rails application you just generated; in that case, be sure to add blacklight devise and the development/test group per below:
 
 <pre>
-source 'http://rubygems.org'
-
-gem 'rails', '~>3.1.3'
-
-gem 'blacklight', '~> 3.2'
-
-
-# We will assume that you're using sqlite3 for testing/demo,
-# but in a production setup you probably want to use a real sql database like mysql or postgres
-gem 'sqlite3'
-
-#  We will assume you're using devise in tutorials/documentation.
-# You are free to implement your own User/Authentication solution in its place.
-gem 'devise'
-
-# For testing.  You will probably want to use all of these to run the tests you write for your hydra head
-group :development, :test do
-  gem 'bcrypt-ruby'
-  gem 'capybara'
-  gem 'cucumber-rails'
-  gem 'database_cleaner'
-  gem 'factory_girl'
-  gem 'mocha'
-  gem 'rspec'
-  gem 'rspec-rails', '>=2.5.0'
-  gem 'ruby-debug'
-  gem 'sqlite3'
-  gem "jettywrapper"
-end # (leave this comment here to catch a stray line inserted by blacklight!)
+  source 'http://rubygems.org'
+
+  gem 'rails', '~> 3.2'
+  gem 'blacklight', '~> 3.3'
+  gem 'atrium', :path => '../../'
+
+  gem 'cancan'
+  gem 'jquery-rails'
+  gem 'json'
+
+  group :assets do
+    gem 'coffee-rails', '~> 3.2.1'
+    gem 'sass-rails',  '~> 3.2.3'
+    gem 'therubyracer', :platforms => :ruby
+    gem 'uglifier', '>= 1.0.3'
+  end
+
+  # For testing
+  group :development, :test do
+    gem 'bcrypt-ruby'
+    gem 'capybara'
+    gem 'cucumber-rails'
+    gem 'database_cleaner'
+    gem 'factory_girl',  '~> 1.1'
+    gem 'mocha'
+    gem 'rspec'
+    gem 'rspec-rails', '>=2.5.0'
+    gem 'ruby-debug'
+    gem 'sqlite3'
+  end
+  gem "devise"
+  gem "compass-rails", "~> 1.0.0", :group => :assets
+  gem "compass-susy-plugin", "~> 0.9.0", :group => :assets
+
 </pre>
 
 To install all of the dependencies, run:
@@ -81,11 +79,7 @@ On some systems, you will have to install system libraries that various gems rel
 
 h3. Run the generators and migrations:
 
-Run the blacklight generator
-
-<pre>rails g blacklight --devise</pre>
-
-Run the atrium generator
+Run the Atrium generator
 
 <pre>rails g atrium -df</pre>
 
@@ -98,12 +92,11 @@ rake db:test:prepare
 
 h3. You're done.
 
-Congratulations.  You've set up the code for your Atrium.
-
-Read "Tools for Developing and Testing":http://hudson.projecthydra.org/job/hydra-head-rails3-plugin/Documentation/file.Tools.html, then read "How to Get Started":http://hudson.projecthydra.org/job/hydra-head-rails3-plugin/Documentation/file.HOW_TO_GET_STARTED.html to get a sense of what you can do with your Hydra Head.
+Congratulations.  You've set up the code to create atrium application.
 
 h2. Modifying and Testing the Atrium Gem
 
-#TODO
 
 h2. Acknowledgements
+
+h3. Design & Strategic Contributions

data/Gemfile.lock

@@ -251,6 +251,7 @@ GEM
       ruby-debug-base (~> 0.10.4.0)
     ruby-debug-base (0.10.4)
       linecache (>= 0.3)
+    ruby_gntp (0.3.4)
     rubyzip (0.9.5)
     sanitize (2.0.3)
       nokogiri (>= 1.4.4, < 1.6)
@@ -317,4 +318,5 @@ DEPENDENCIES
   rspec-rails (>= 2.0.0)
   ruby-debug
   ruby-debug-base
+  ruby_gntp
   sqlite3

data/README.mkd

@@ -1,56 +1,66 @@
 # Atrium
 
-__Atrium is still a work in progress. Do not count on any of the present or
-promised functionality to exist.__
+## A note from the developers
 
+_0.0.1 is an alpha release. Treat it accordingly_
 
-## What it's for
+_"master" is going through a major refactor. THINGS MAY BREAK. THE WORLD MAY
+END_
+
+Atrium is a project that has been gestating for a while. Consider the present
+state of the code a proof-of-concept implementation. There are lots of things we
+would do differently if we started over again. For more information see
+`ROADMAP.mkd`. The development process is coordinated in a [public-facing
+JIRA][1]
 
-Atrium is a tool for:
+## What it's for
 
-  - grouping items
-  - adding context
+Atrium is a tool for extending a [Blacklight][2]-enabled application by:
 
-to an index in a [Blacklight][1]-enabled application.
+  - Grouping items
+  - Adding context
+  - Customizing presentation
 
-Atrium provides three mechanisms to achieve this end:
+Atrium provides four mechanisms to achieve this end:
 
   - Collections
   - Exhibits
   - Showcases
-
+  - Themes
 
 ### Collections
-
 A collection contains a subset of the items in the complete index as defined by
 a Solr query. An explicitly declared subset of the total facets can be applied
 to these items. A collection description and or featured items form the
 collection can be displayed at the top level collection page. Collections can be
 themed independently of the base application and other collections.
 
-
 ### Exhibits
-
 An exhibit is a customizable view of a single topic (as defined by a facet),
 further scoped by an optional Solr query. An exhibit defines it's own
 hierarchical list of facets. An exhibit may also have a description and a list
 of featured items.
 
-
 ### Showcases
-
 A showcase is a container for storing feature items and descriptions. A showcase
 can be attached to a collection, exhibit, or to specific combinations of
 selected facets and facet values within an exhibit. There can be multiple
 showcases in an exhibit.
 
+### Themes
+At present, themes are a wrapper around the existing rails templating system. A
+theme is simply a [nested layout][3] that works in conjunction with some `yeild`
+blocks in the base atrium layout. This is a pretty flexible solution but
+requires the implementer to know how layouts and rendering work in Rails. It
+also means you have to re-deploy the application every time you want to change
+how it looks.
 
 ## Acknowledgements
-
-Thanks to [Hiten Parmar][2] for the gem name. The [origional atirum gem][3] was
+Thanks to [Hiten Parmar][4] for the gem name. The [original atrium gem][5] was
 an instant web server.
 
-
-[1]: https://github.com/projectblacklight/blacklight
-[2]: http://www.hitenparmar.com/
-[3]: https://github.com/hrp/atrium
+[1]: https://jira.duraspace.org/browse/HYGALL
+[2]: https://github.com/projectblacklight/blacklight
+[3]: http://guides.rubyonrails.org/layouts_and_rendering.html#using-nested-layouts
+[4]: http://www.hitenparmar.com/
+[5]: https://github.com/hrp/atrium

data/ROADMAP.mkd

@@ -0,0 +1,92 @@
+# Development Roadmap
+
+The following issues need to be addressed before it would be considered a 1.0
+release candidate:
+
+### Atrium should be a mountable Rails engine -- but isn't
+Atrium was based on an early version of [hydra-head][1] which, in turn, shared
+code with [Blacklight][5] which was a Rails 2 plugin at the time. As such the
+integration points between Atrium and the host Rails application are not
+following the present best practices. Atrium should be refactored to be an
+[isolated engine][2].
+
+### Atrium overrides and extends the Blacklight catalog a lot -- and shouldn't
+Parts of Atrium rely on the Blacklight catalog controller to return collections
+of Solr documents. This is a messy process and tightly couples Atrium to
+Blacklight in undesirable ways. Now that [Blacklight][5] provides Solr helper
+methods for both the Lucene query handler as well as the DisMax query handler we
+should be able to avoid this problem.
+
+### The routs are ugly
+The routes of an application is it's public API. They should be human-readable
+and should try to conform to be [resourceful][3] whenever possible. The routes
+in Atrium will be overhauled when the gem is converted to a modern Rails engine.
+The days of `/atrium_*` are numbered. Bonus points if collections have a
+[frendliy_id][4] style identifier. See `doc/Routing.mdown` for more.
+
+### Keeping track of the internal application state is fragile
+The application behaves as it should under normal circumstances but it lacks
+resilience. This stems from the complexity of interacting with the same data in
+Atrium in several modes of operation:
+  - Searching the entire holdings
+  - Searching a collection
+  - Browsing a collection
+  - Modifying a collection while searching
+  - Modifying a collection while browsing
+  - Selecting items within a collection in a modal window
+  - Setting a scope within the holdings for a collection
+  - Setting a scope within a collection for an exhibit
+Determining which of these states the user is presently in is accomplished with
+a combination of session storage and passing params around in the URL. The
+resulting experience doesn't inspire confidence. Params can accumulate
+unintentionally. Session variables change while interacting with the site in
+more than one browser tab. It isn't always clear why things are the way they are
+now.
+
+Some of these issues may be able to be addressed with better routes but
+preventing these kinds of problems entirely will require refactoring a lot of
+the application logic to make stateless interactions possible.
+
+### The management interface is confusing
+There is a collision of concerns when managing a collection and the exhibits and
+showcases it contains. Keeping all of the possible customizations straight and
+conveying _what they actually mean_ hasn't been done effectively. There are lots
+of little changes that could be made to the present interface that would make a
+difference but more dramatic refactoring may be required to achieve the desired
+result.
+
+### The theming and templating options are underwhelming
+In order to make significant changes in the look and feel of a collection in
+Atrium you will need to know HTML, CSS, be familiar with [how Rails renders
+views][6], understand how to configure [Blacklight][5], and have a working
+knowledge how to index things into Solr. That's a pretty high barrier to entry.
+This isn't necessarily a problem if Atrium is a toolkit for developers familiar
+with Blacklight who are creating digital exhibits. However, if Atrium would like
+to provide a turn-key solution that can be easily customized from within the
+application by someone without a firm grasp of web technologies then we have a
+long way to go.
+
+Allowing the look and feel of a collection to be significantly modified from the
+frontend itself would require a lot of work. Our best guess as to how this
+problem should be approached is by adding another templating layer in the view
+rendering stack. Development stalled on this over concerns about the feasibility
+of rendering the contents of Blacklight partials in custom Liquid tags. We
+should be able to get this approach to work for the browse views as long as
+we're relying on Blacklight to just provide collections of Solr documents. See
+`doc/Theming.mdown` for more.
+
+The [Asset Pipeline][7] is great but because assets should be pre-compiled for
+production use we would have to support an alternative solution for providing
+custom, collection-specific CSS.
+
+It boils down to choosing the audience that Atrium is trying to serve. Should we
+even be trying to compete with [Omeka][8]?
+
+[1]:  https://github.com/projecthydra/hydra-head
+[2]:  http://api.rubyonrails.org/classes/Rails/Engine.html#label-Isolated+Engine
+[3]:  https://rubygems.org/gems/friendly_id
+[4]:  http://guides.rubyonrails.org/routing.html#resources-on-the-web
+[5]:  https://github.com/projectblacklight/blacklight
+[6]:  http://guides.rubyonrails.org/layouts_and_rendering.html
+[7]:  http://guides.rubyonrails.org/asset_pipeline.html
+[8]:  http://omeka.org/

data/app/assets/javascripts/atrium/atrium.js

@@ -164,6 +164,25 @@
        });
     });
 
+    $("a.remove_featured", this).live("click", function(e) {
+       var $docNode = $(this).closest('div.document')
+       var url = $(this).attr('action');
+       $.ajax({
+         type: "POST",
+         url: url,
+         dataType: "html",
+         beforeSend: function() {
+   			$docNode.animate({'backgroundColor':'#fb6c6c'},300);
+         },
+         success: function(data) {
+           $docNode.slideUp(300,function() {
+             $docNode.remove();
+           });
+           //$("#show-selected").before('<div id="flash_notice"> data </div>'); // This could be implemented better
+         }
+       });
+    });
+
     $('.edit-text').editable(submitEditableText,{
          indicator : 'Saving...',
          tooltip   : 'Click to edit...'

data/app/assets/stylesheets/atrium/atrium.css

@@ -4,6 +4,8 @@ body {
   padding:0;
 }
 
+.warning { color: red !important;}
+
 #doc, #doc2, #doc3, #doc4 {
   border-top:5px solid #484748;
 }

data/app/controllers/atrium/collections_controller.rb

@@ -21,7 +21,6 @@ class Atrium::CollectionsController < Atrium::BaseController
   end
 
   def set_collection_scope
-    logger.error("into scoping")
     session[:copy_folder_document_ids] = session[:folder_document_ids]
     session[:folder_document_ids] = []
     @atrium_collection = Atrium::Collection.find(params[:id])
@@ -52,21 +51,12 @@ class Atrium::CollectionsController < Atrium::BaseController
       @atrium_collection= Atrium::Collection.find(params[:id])
       @atrium_showcase= Atrium::Showcase.with_selected_facets(@atrium_collection.id,@atrium_collection.class.name, params[:f]).first
     end
-
-    if @atrium_collection && @atrium_collection.filter_query_params && @atrium_collection.filter_query_params[:solr_doc_ids]
-
-      items_document_ids = @atrium_collection.filter_query_params[:solr_doc_ids].split(',')
-      @collection_items_response, @collection_items_documents = get_solr_response_for_field_values("id",items_document_ids || [])
-    end
+    @collection_items_response, @collection_items_documents=get_solr_documents_from_asset(@atrium_collection)
     if(params[:showcase_id] && @atrium_showcase.nil?)
       @atrium_showcase = Atrium::Showcase.find(params[:showcase_id])
     end
-    if @atrium_showcase && !@atrium_showcase.showcase_items[:solr_doc_ids].nil?
-      selected_document_ids = @atrium_showcase.showcase_items[:solr_doc_ids].split(',')
-      @featured_response, @featured_documents = get_solr_response_for_field_values("id",selected_document_ids || [])
-    end
+    @featured_response, @featured_documents=get_solr_documents_from_asset(@atrium_showcase) unless @atrium_showcase.nil?
     @description_hash=get_description_for_showcase(@atrium_showcase) unless @atrium_showcase.nil?
-
   end
 
   def edit

data/app/controllers/atrium/exhibits_controller.rb

@@ -34,23 +34,11 @@ class Atrium::ExhibitsController < Atrium::BaseController
   def show
     #get children of emission dates
     @members = get_all_children(@browse_document_list, "is_member_of_s")
-    @exhibit= Atrium::Exhibit.find(params[:id])
+    @exhibit= Atrium::Exhibit.find(params[:id]) unless @exhibit
     @exhibit_navigation_data = get_exhibit_navigation_data
-    if @exhibit && @exhibit.filter_query_params && @exhibit.filter_query_params[:solr_doc_ids]
-
-      items_document_ids = @exhibit.filter_query_params[:solr_doc_ids].split(',')
-
-      @collection_items_response, @collection_items_documents = get_solr_response_for_field_values("id",items_document_ids || [])
-    end
-
-
+    @collection_items_response, @collection_items_documents=get_solr_documents_from_asset(@exhibit)
     @atrium_showcase=Atrium::Showcase.with_selected_facets(@exhibit.id, @exhibit.class.name, params[:f]).first
-    if @atrium_showcase && !@atrium_showcase.showcase_items[:solr_doc_ids].nil?
-
-      selected_document_ids = @atrium_showcase.showcase_items[:solr_doc_ids].split(',')
-
-      @featured_response, @featured_documents = get_solr_response_for_field_values("id",selected_document_ids || [])
-    end
+    @featured_response, @featured_documents=get_solr_documents_from_asset(@atrium_showcase) unless @atrium_showcase.nil?
     @description_hash=get_description_for_showcase(@atrium_showcase) unless @atrium_showcase.nil?
     if params[:no_layout]
       render :layout=>false
@@ -99,8 +87,8 @@ private
 
 def determine_collection_id
   if params[:id]
-    exhibit = Atrium::Exhibit.find(params[:id])
-    collection_id = exhibit.atrium_collection_id if exhibit
+    @exhibit = Atrium::Exhibit.find(params[:id])
+    collection_id = @exhibit.atrium_collection_id if @exhibit
   end
   return collection_id
 end