CiteroEngine Engine Gem

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:

mount CiteroEngine::Engine, :at => '/MOUNT_LOCATION'

You'll need to require the jquery-rails gem also.

In your Gemfile

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

CiteroEngine.easybib
CiteroEngine.refworks
CiteroEngine.endnote

The available options are as follow, with available defaults shown

: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

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 ActiveRecord, 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

ex_cite