citero_engine 3.0.0.alpha

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ffa88a8a357723e174633e79ff08dd9f9ea746d9
+  data.tar.gz: ff31e9b0c4d87298f5f6955244a30b66ce7df705
+SHA512:
+  metadata.gz: 479e5cacf4d085166b8a20be9fb5e5f5eb262ed7040a083e0ba747ec13ee70eb48a925ccd86c6517eec9f69598d540229ce965ac6371967a5557e9f3645e3d3f
+  data.tar.gz: 6449dbcb3be1a90abd2f43eaa0fa9a8cdecde5685330665ec9fdb327e908fec5541e4b6d700a70068c2542693e9eff93037fb71168708685057e7c3b1f4d9990

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 NYU Division of Libraries
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,105 @@
+CiteroEngine Engine Gem
+======================
+[![Build Status](http://jenkins.library.nyu.edu/buildStatus/icon?job=citero_engine Staging Test)](http://jenkins.library.nyu.edu/view/Citero/job/citero_engine%20Staging%20Test/)
+[![Build Status](https://travis-ci.org/NYULibraries/citero_engine.png?branch=master)](https://travis-ci.org/NYULibraries/citero_engine)
+[![CircleCI](https://circleci.com/gh/NYULibraries/citero_engine.svg?style=svg)](https://circleci.com/gh/NYULibraries/citero_engine)
+[![Coverage Status](https://coveralls.io/repos/NYULibraries/citero_engine/badge.png?branch=master)](https://coveralls.io/r/NYULibraries/citero_engine?branch=master)
+[![Dependency Status](https://gemnasium.com/NYULibraries/citero_engine.png)](https://gemnasium.com/NYULibraries/citero_engine)
+[![Gem Version](https://badge.fury.io/rb/citero_engine.png)](http://badge.fury.io/rb/citero_engine)
+[![Code Climate](https://codeclimate.com/github/NYULibraries/citero_engine.png)](https://codeclimate.com/github/NYULibraries/citero_engine)
+
+A JRuby wrapper for the citero tool, enables use of the citero tool in JRuby distributed as a Rails 3 Engine Gem.
+
+Install
+==========
+
+Mount the engine gem to your rails project like so:
+
+```ruby
+mount CiteroEngine::Engine, :at => '/MOUNT_LOCATION'
+```
+
+You'll need to require the [jquery-rails](https://github.com/rails/jquery-rails) gem also.
+
+In your Gemfile
+
+```ruby
+gem "jquery-rails"
+```
+
+Formats supported
+========
+Currently supporting PNX, RIS, CSF, BiBTeX, OpenURL, XERXES_XML, and EasyBib JSON.
+
+Currently supports the following services RefWorks, EasyBib, EndNote.
+
+
+How to use
+========
+
+There are two methods to use this engine. To use the ActiveRecord method, first you must have a record that implements acts\_as\_citable.  
+
+Otherwise, you can POST or GET to /MOUNT\_LOCATION/export_citations(/:to_format)(/:id) with the parameters data[] and from\_format[] defined.
+The data[] array and the from\_format[] array must correspond to each other, that is, each element, e, in data[] is of from\_format format[e].
+
+Finally, you can send an OpenURL request, simply define the :to_format and pass in the query string.
+
+Services
+========
+
+Some services, such as Endnote, RefWorks, and EasyBib are already included in citero_engine. These services are configurable right out of the box for your needs.
+
+There are two ways to use services, rendering and redirect. The render method will render a view with a 200 response, and the redirect will, as expected,
+redirect to another page with a 302 response.
+
+To configure a built-in service, such as Endnote, Refworks, or EasyBib, simply modify the following objects
+
+```ruby
+CiteroEngine.easybib
+CiteroEngine.refworks
+CiteroEngine.endnote
+```
+
+The available options are as follow, with available defaults shown
+
+```ruby
+:name				=> 	'Service' # What you want to call this service, and how it will be accessed, i.e. 'easybibpush'
+:to_format			=>	# The format that the service is expecting
+:action				=>	'render' # Either :redirect or :render is supported
+:template			=>	'citero_engine/cite/external_form' # The template view to render. You are free to use your own, citero_engine provides one for free!
+:url				=>	# The url to redirect to or the url to send the form to
+:method				=>	'POST' # This is the form action
+:enctype			=>	'application/x-www-form-urlencoded' # This is the enctype for the form
+:element_name		=> 	'data' # The default view constructs a form that automatically posts, this is the name of the textbox.
+:callback_protocol	=>	:http # The protocol the callback url is to use for this application. Defaults to :http, supports :https
+
+alias :protocol :callback_protocol	# An alias, should you wish to use this outdated version.
+```
+To add a new service, simply
+
+```ruby
+easybib = PushFormat.new( :name => :easybibpush, :to_format => :easybib, :action => :render, :template => "citero_engine/cite/external_form", :url => "http://www.easybib.com/cite/bulk")
+CiteroEngine.push_formats['easybib'] = easybib
+```
+Examples
+========
+
+Mounted at root (/)
+
+    GET, POST (ActiveRecord, will download RIS)
+    http://localhost:3000/export_citations?to_format=ris&id[]=1
+    http://localhost:3000/export_citations/ris/1
+
+    GET, POST (ActiveRecord, will push to refworks)
+    http://localhost:3000/export_citations?to_format=refworks&id[]=1
+    http://localhost:3000/export_citations/refworks/1
+
+    GET, POST (Non ActiveRecord, will download RIS)
+    http://localhost:3000/export_citations?to_format=ris&from_format[]=csf&from_format[]=csf&data[]=itemType%3A%20book&data[]=itemType%3A%20journalArticle
+    GET, POST (Non ActiveRecord, will push to refworks)
+    http://localhost:3000/export_citations?to_format=refworks&from_format[]=csf&from_format[]=csf&data[]=itemType%3A%20book&data[]=itemType%3A%20journalArticle
+
+    OpenURL (Non ActiveRecord, will download RIS)
+    http://localhost:3000/export_citations?to_format=ris&url_ver=Z39.88-2004&url_ctx_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Actx&ctx_ver=Z39.88-2004&ctx_tim=2012-11-20T13%3A40%3A11-05%3A00&ctx_id=&ctx_enc=info%3Aofi%2Fenc%3AUTF-8&rft.genre=journal&rft.issn=0893-3456&rft.jtitle=Los+Alamos+monitor&rft.language=eng&rft.object_id=991042747005504&rft.object_type=JOURNAL&rft.page=1&rft.place=Los+Alamos%2C+N.M.&rft.pub=%5BH.+Markley+McMahon%5D&rft.stitle=ALAMOS+MONITOR+%28LOS+ALAMOS%2C+NM%29&rft.title=Los+Alamos+monitor&rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Ajournal&rft_id=L&req.ip=127.0.0.1
+    OpenURL (Non AciveRecord, will push to refworks)
+    http://localhost:3000/export_citations?to_format=refworks&url_ver=Z39.88-2004&url_ctx_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Actx&ctx_ver=Z39.88-2004&ctx_tim=2012-11-20T13%3A40%3A11-05%3A00&ctx_id=&ctx_enc=info%3Aofi%2Fenc%3AUTF-8&rft.genre=journal&rft.issn=0893-3456&rft.jtitle=Los+Alamos+monitor&rft.language=eng&rft.object_id=991042747005504&rft.object_type=JOURNAL&rft.page=1&rft.place=Los+Alamos%2C+N.M.&rft.pub=%5BH.+Markley+McMahon%5D&rft.stitle=ALAMOS+MONITOR+%28LOS+ALAMOS%2C+NM%29&rft.title=Los+Alamos+monitor&rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Ajournal&rft_id=L&req.ip=127.0.0.1

data/Rakefile

@@ -0,0 +1,46 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title    = 'CiteroEngine'
+  rdoc.options << '--line-numbers'
+  rdoc.options << '--markup markdown'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('app/**/*.rb')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.ruby_opts = "--debug --dev"
+end
+task default: :spec

data/app/assets/javascripts/citero_engine.js

@@ -0,0 +1,6 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// This engine requires jquery.
+//= require jquery
+//= require_tree './citero_engine'

data/app/assets/javascripts/citero_engine/submit_external_form.js

@@ -0,0 +1,12 @@
+// A simple function to allow us to automatically submit forms for 
+// pushing to other services such as EasyBib and RefWorks.
+jQuery(document).ready(function($) {
+	submit_external_form();
+	// Automatically submit the form.
+	function submit_external_form() {
+		// Hide the page
+		$("body").hide();
+		$form = $(".external_form");
+		$form.trigger("submit");
+	}
+});

data/app/controllers/citero_engine/citero_engine_controller.rb

@@ -0,0 +1,190 @@
+require "citero_engine/engine"
+require 'digest/sha1'
+require 'open-uri'
+module CiteroEngine
+  # Logic behind the webservice. First it gathers all the resource keys and creates Citation objects out of them and then
+  # it gathers any and all from formats and data variables that were sent via post and creates an array out of them. If the
+  # array is still empty it uses the URL as an OpenURL. It then loops through the array and translates and caches (or fetches)
+  # each one using acts_as_citable. It then either downloads the data or redirects to another webservice.
+  class CiteroEngineController < ActionController::Base
+    # There must be a destination format, or else this whole thing doesnt make sense
+    before_filter :valid_to_format?
+    layout "citero_engine/application"
+
+    # Sends bad request if there is no destination format
+    def valid_to_format?
+      head :bad_request unless to_format
+    end
+
+    # Checks to see if destination format is valid and stores it in a class variable
+    def to_format
+      @to_format ||= whitelist_formats :to, params[:to_format]
+    end
+    private :to_format
+
+    # Constructs an array containing all the citations
+    def citations
+     unless defined? @citations
+      @citations = record_citation + resource_citation + format_citation
+      if @citations.empty?
+        @citations << open_url_citation
+      end
+     end
+     @citations.compact
+    end
+
+    def record_citation
+      (params[:id].nil?) ? [] :
+        params[:id].collect do |id|
+          record = CiteroEngine.acts_as_citable_class.find_by_id id if CiteroEngine.acts_as_citable_class.respond_to? :find_by_id
+          (record.nil?) ? (raise(ArgumentError, "This ID cannot be found.")) : record
+        end
+    end
+
+    # Constructs new citation objects with only the citation key set, returns an array
+    def resource_citation
+      resources = []
+      return resources if params[:resource_key].nil?
+      resources << Rails.cache.fetch(params[:resource_key])
+      resources.flatten!
+      resources.collect do |key|
+        citation = CiteroEngine.acts_as_citable_class.new()
+        citation.resource_key = key
+        citation
+      end
+    end
+
+    # Constructs new citation objects with data and source format set (the citation key is constructed automatically), returns an array
+    def format_citation
+      (params[:from_format].nil? || params[:data].nil?) ? [] :
+        params[:from_format].collect.with_index do |format, index|
+          CiteroEngine.acts_as_citable_class.new  CiteroEngine.acts_as_citable_class.data_field.to_sym => params[:data].to_a[index],   CiteroEngine.acts_as_citable_class.format_field.to_sym => (whitelist_formats :from, format)
+        end
+    end
+
+    # Returns a single citation object with data and format set as the url and openurl respectively
+    def open_url_citation
+      CiteroEngine.acts_as_citable_class.new   CiteroEngine.acts_as_citable_class.data_field.to_sym => CGI::unescape(request.protocol+request.host_with_port+request.fullpath),   CiteroEngine.acts_as_citable_class.format_field.to_sym => (whitelist_formats :from, 'openurl')
+    end
+
+    # Maps the output and caches it, alternatively it fetches the already cached result. Seperates each output with two new lines.
+    # Raises an argument error if any error is caught in mapping (usually the formats are messed up)
+    def map
+      @output ||= citations.collect { |citation| Rails.cache.fetch(citation.resource_key+to_format) { citation.send(to_format) } }.join_and_enclose *delimiters
+    rescue Exception => exc
+      raise ArgumentError, "#{exc}\n Data or source format not provided and/or mismatched. [citations => #{citations}, to_format => #{@to_format}]  "
+    end
+
+    # Maps then decides wether its a push request or a download, catches all bad argument errors
+    def index
+      map
+      serve
+    rescue ArgumentError => exc
+      handle_invalid_arguments exc
+    end
+
+    # Pushes to a web service if that is what was requested else it downloads
+    def serve
+      @push_to ? push : download
+    end
+
+    # Cleans the user input and finds the associated method for that format
+    def whitelist_formats direction, format
+      # if the params are nil then it returns nil
+      if direction.nil? || format.nil?
+        return
+      end
+      # if the to format is found, it returns the method name for that to format
+      format_sym = format.downcase.to_sym
+      if (direction == :to && (Citero.to_formats.include?(format_sym) || Citero.citation_styles.include?(format_sym)))
+        return "to_#{format_sym}"
+      # if the from format is found, it returns just that because the object already knows what method to call
+      elsif (direction == :from && Citero.from_formats.include?(format_sym))
+        return format.downcase
+      end
+      # if the format is still not found, it might be a push request, check if that is the case
+      if CiteroEngine.push_formats.include? format_sym
+        @push_to = CiteroEngine.push_formats[format_sym]
+        @to_format = @push_to.to_format.downcase
+        return "#{direction.to_s}_#{@to_format}"
+      end
+    end
+
+    # For debugging purposes prints out the error. Also sends bad request header
+    def handle_invalid_arguments exc
+      logger.debug exc
+      head :bad_request
+    end
+
+    # Redirects or calls a predefined method depending on the webservice selected
+    def push
+      # for redirects
+      if @push_to.action.eql? :redirect
+        # Openurl is data
+        @data = "#{request.protocol}#{request.host_with_port}#{request.fullpath}"
+        # and redirect to the url supplied by the webservice and the callback url
+        redirect_to @push_to.url+callback, :status => 303
+      elsif @push_to.action.eql? :render
+        # call the method this service needs
+        render_push
+      end
+    end
+
+    # sends the data with utf-8 encoding
+    def download
+      send_data @output.force_encoding('UTF-8'), :filename => filename, :type => @to_format.formatize.to_sym
+    end
+
+    # The callback url is defined here
+    def callback
+      # Starts with current url minus the querystring..
+      callback = "#{export_citations_url.gsub(/https?/, @push_to.callback_protocol.to_s)}?"
+      resource_keys = []
+      citations.each do |citation|
+        if !citation.respond_to? :new_record || citation.new_record?
+          resource_keys << citation.resource_key
+        end
+      end
+      unless resource_keys.empty?
+        resource_key = Digest::SHA1.hexdigest(resource_keys.sort.join)
+        Rails.cache.write(resource_key,resource_keys)
+        callback += "resource_key=#{resource_key}&"
+      end
+      citations.each do |citation|
+        # then adds a resource key for each cached resource
+        callback += (!citation.respond_to? :new_record || citation.new_record?) ? "" : "id[]=#{citation.id}&"
+      end
+      # and finally the to format
+      callback += "to_format=#{@to_format.formatize}"
+      # url encode and return
+      ERB::Util.url_encode(callback)
+    end
+
+    # Creates the filename and extension. Few are application specific
+    def filename
+      name = "export"
+      case @to_format
+      when "to_bibtex"
+        name += ".bib"
+      when "to_easybib"
+        name += ".json"
+      else
+        name += "." + @to_format.formatize
+      end
+      name
+    end
+
+    def render_push
+      render :layout => false, :template => @push_to.template
+    end
+
+    def delimiters
+      case @to_format
+      when "to_easybib"
+        return [",\n","[","]"]
+      else
+        return ["\n\n"]
+      end
+    end
+  end
+end

data/app/helpers/citero_engine/application_helper.rb

@@ -0,0 +1,7 @@
+module CiteroEngine
+  module ApplicationHelper
+    def build_external_form
+      return "<textarea name=\"#{@push_to.element_name}\" id=\"#{@push_to.element_name}\">#{@output}</textarea>"
+    end
+  end
+end

data/app/models/citero_engine/citation.rb

@@ -0,0 +1,17 @@
+module CiteroEngine
+  # Citation class, holds data from format and/or resource key
+  class Citation
+    extend ActsAsCitable
+    include ResourceKey
+    # Required fields
+    attr_accessor :data, :from_format
+    acts_as_citable do |c|
+      c.format_field = :from_format
+    end
+    def initialize args = {}
+      self.data = args[:data]
+      self.from_format = args[:from_format]
+      self.resource_key = args[:resource_key]
+    end
+  end
+end

data/app/models/citero_engine/push_format.rb

@@ -0,0 +1,19 @@
+module CiteroEngine
+  # Citation class, holds data from format and/or resource key
+  class PushFormat
+    # Required fields
+    attr_accessor :name, :to_format, :action, :template, :url, :method, :enctype, :element_name, :callback_protocol
+    alias :protocol= :callback_protocol=
+    def initialize args = {}
+      self.name = (args[:name] or 'Service')
+      self.to_format = args[:to_format]
+      self.action = (args[:action] or :render)
+      self.template = (args[:template] or "citero_engine/cite/external_form")
+      self.url = args[:url]
+      self.method = (args[:method] or "POST")
+      self.enctype = (args[:enctype] or "application/x-www-form-urlencoded")
+      self.element_name = (args[:element_name] or "data")
+      self.callback_protocol = (args[:protocol] or :http)
+    end
+  end
+end

data/app/models/citero_engine/resource_key.rb

@@ -0,0 +1,13 @@
+module CiteroEngine
+  module ResourceKey
+    def self.included(klass)
+      klass.class_eval do
+        attr_writer :resource_key
+      end
+    end
+    # Construct a resource key if it doesn't already exist
+    def resource_key 
+      @resource_key ||= Digest::SHA1.hexdigest(_data)
+    end
+  end
+end