Merge pull request #17 from mlibrary/update-readme-documentation

Updated readme documentation, added a Hyrax section

README.md

@@ -6,11 +6,13 @@ More information about IRUS-UK can be found at [http://www.irus.mimas.ac.uk/](ht
 
 This gem was developed for use with a Hyrax repository [http://samvera.org/](http://samvera.org/), but it can be used with any other web application supporting Ruby gems. 
 
+More information on COUNTER reports and reporting can be found at [Project COUNTER](https://www.projectcounter.org/)
+
 ## Build Status
 ![Build Status](https://api.travis-ci.org/uohull/irus_analytics.png?branch=master)
 ## Prerequisite
 
-Blacklight OAI Provider
+[Blacklight OAI Provider](https://github.com/projectblacklight/blacklight_oai_provider) or some other method of displaying an OAI feed of your works or digital objects. While the irus_analytics gem will push limited usage data to IRUS-UK, they still need a way to harvest your repository metadata (like Title, Author, etc) to create COUNTER usage reports.
 
 ## Installation
 
@@ -100,7 +102,7 @@ production:
 
 
 ### Integration
-The IrusAnalytics code is designed to be called after an Investigation (view) or Request (download) events has happened in your application. The following code added to the Rails controller handles the content download.
+The IrusAnalytics code is designed to be called after an Investigation (view) or Request (download) event has happened in your application. The following code added to the Rails controller handles the content download.
 
 To add request handling to a controller, run the following:
 
@@ -178,7 +180,8 @@ module Hyrax
     # begin inject IrusAnalytics::InjectControllerHooksGenerator: item_identifier_for_irus_analytics
     def item_identifier_for_irus_analytics
       # return the OAI identifier
-      curation_concern.oai_identifier
+      # http://www.openarchives.org/OAI/2.0/guidelines-oai-identifier.htm
+      CatalogController.blacklight_config.oai[:provider][:record_prefix] + ":" + params[:id]
     end
     # end inject IrusAnalytics::InjectControllerHooksGenerator: item_identifier_for_irus_analytics
     # begin inject IrusAnalytics::InjectControllerHooksGenerator: skip_send_irus_analytics?
@@ -194,9 +197,6 @@ module Hyrax
     # end inject IrusAnalytics::InjectControllerHooksGenerator: skip_send_irus_analytics?
 
 
-
-
-
     #include Hyrax::BreadcrumbsForWorks
     self.curation_concern_type = ::Dissertation
 
@@ -216,9 +216,12 @@ Therefore in summary...
     after_filter :send_analytics, only: [:show]
 
     def item_identifier_for_irus_analytics
+      CatalogController.blacklight_config.oai[:provider][:record_prefix] + ":" + params[:id]
     end
 
-... needs adding to the relevant controller.  
+... needs adding to the relevant controller.
+
+NOTE: If you are not using the [Blacklight OAI Provider](https://github.com/projectblacklight/blacklight_oai_provider) gem to create your OAI feed, you'll need to modify the `item_identifier_for_irus_analytics` method to conform with your application's [OAI identifiers](http://www.openarchives.org/OAI/2.0/guidelines-oai-identifier.htm).
 
 To be compliant with the IRUS-UK client requirements/recommendations this Gem makes use of the Resque  [https://github.com/resque/resque](https://github.com/resque/resque).  Resque provides a simple way to create background jobs within your Ruby application, and is specifically used within this gem to push the analytics posts onto a queue.  This means the download functionality within your application is unaffected by the send analytics call, and it provides a means of queuing analytics if the IRUS-UK server is down. 
 
@@ -234,6 +237,52 @@ To start the resque background job for this gem use
 
     QUEUE=irus_analytics rake environment resque:work
 
+## Additional Notes for Hyrax
+
+In a Hyrax application, the `Hyrax::DownloadsController` and `Hyrax::FileSetsController` will be in the Hyrax gem itself so the irus_analytics generator will not write to them. One can copy the entirety of these classes (and relevent specs) into one's application or can use the Module#Prepend pattern to add/modify the neccessary methods. An example for how to do this in Hyrax for a Presenter (but the idea is the same for Controllers) is here, https://samvera.github.io/patterns-presenters.html#overriding-and-custom-presenter-methods, or try something like:
+
+```
+# app/controllers/concerns/download_override.rb (or whatever convention you use)
+
+Hyrax::DownloadsController.class_eval do
+  prepend(DownloadsControllerBehavior = Module.new do
+    include IrusAnalytics::Controller::AnalyticsBehaviour
+
+    # Render the 404 page if the file doesn't exist.
+    # Otherwise renders the file.
+    def show
+      case file
+      when ActiveFedora::File
+        # For original files that are stored in fedora
+        send_irus_analytics_request
+        super
+      when String
+        # For derivatives stored on the local file system
+        send_local_content
+      else
+        raise Hyrax::ObjectNotFoundError
+      end
+    end
+
+    def item_identifier_for_irus_analytics
+      # return the OAI identifier
+      CatalogController.blacklight_config.oai[:provider][:record_prefix] + ":" + FileSet.find(params[:id]).parent.id
+    end
+  end
+end
+```
+
+where we add the `item_identifier_for_irus_analytics` method which reports the parent's or work's OAI identifier and we explicitly call the `send_irus_analytics_request` method only for Fedora downloads, not for derivatives like thumbnails since those are explicitly not considered Requests per COUNTER.
+
+And then in application.rb something like:
+
+```
+config.to_prepare do
+  # ensure overrides are loaded
+  # see https://bibwild.wordpress.com/2016/12/27/a-class_eval-monkey-patching-pattern-with-prepend/
+  Rails.configuration.cache_classes ? require("app/controllers/concerns/download_override.rb") : load("app/controllers/concerns/download_override.rb")
+end
+```
 
 ## Contributing