easy extensions for eprints
Post on 15-Jan-2016
48 Views
Preview:
DESCRIPTION
TRANSCRIPT
Easy Extensions for EPrints
EPrints Training & Support Session 1Open Repositories 2008
Session 1 Overview
Extending EPrints using plugins Introduction to plugins API essentials Walkthrough: ZIP export Walkthrough: Formats report Plugin exercises & EPrints Surgery
Introduction to Plugins
EPrints 3: All Change
3.0 marked new approach for developers
Completely restructured code base Separated into 2 parts:
core facilities framework user capabilities provided by plugins
EPrints 3: All Change (2)
Generic plugin framework “Installed” plugin suite
implements repository functions search, deposit workflow, import/export,
editorial review, user profile, saved searches, admin tools...
“Installed” suite continues to evolve 3.1 introduces QA, bulk editing,
configuration editing...
What This Means
Create new repository behaviour alter, remove or extend plugin suite
Easily share results with community independent of core
Key Benefits
Lightweight buy in for development focus on features not integration not huge learning curve easy to code
Increases scope for community engagement
many more focused development opportunities
small, high value contributions to fit the community profile
Developing Plugins
Core provides API easy access to your repository data
Plugin framework provides simple registration of extensions simple interface for plugins to
implement (the plugin itself does not have be
simple!)
Developing Plugins (2)
Several types of plugin interface provided
Import and export get data in and out
Interface screens user tools and reports
Input components ways for users to enter data
Conversion Issue (3.1 QA)
API Essentials
Accessing Data
Easy access to your repository data Data model contains 3 core objects:
EPrint Document User
Access existing objects or create new ones
Get and set metadata values
Accessing Data: Example
Get title and pub date of an eprint
$eprint = EPrints::DataObj::EPrint
->new( $session, 142 );
Accessing Data: Example
Get title and pub date of an eprint
$eprint = EPrints::DataObj::EPrint
->new( $session, 142 );
print $eprint->get_value( “title” );
Accessing Data: Example
Get title and pub date of an eprint
$eprint = EPrints::DataObj::EPrint
->new( $session, 142 );
print $eprint->get_value( “title” );
if( $eprint->is_set( “date” ) )
{
print $eprint->get_value( “date” );
}
Accessing Data: Example (2)
Change the license of a document
$doc = EPrints::DataObj::Document
->new( $session, 73 );
Accessing Data: Example (2)
Change the license of a document
$doc = EPrints::DataObj::Document
->new( $session, 73 );
$doc->set_value( “license”,
“cc_public_domain” );
Accessing Data: Example (2)
Change the license of a document
$doc = EPrints::DataObj::Document
->new( $session, 73 );
$doc->set_value( “license”,
“cc_public_domain” );
$doc->commit;
Data Collections
Easily manipulate collections of objects
Built-in datasets all data objects of same type or in same state
Searching the repository all data objects matching criteria
Data Collections: Datasets
Corresponding dataset for each data object
eprint document user
Also datasets of eprints in same state
archive inbox buffer deletion
Data Collections: Datasets Example
Get title of every eprint in live archive
$ds = $repository->get_dataset( “archive” );
Data Collections: Datasets Example
Get title of every eprint in live archive
$ds = $repository->get_dataset( “archive” );
$ds->map( $session, \&get_title );
Data Collections: Datasets Example
Get title of every eprint in live archive
$ds = $repository->get_dataset( “archive” );
$ds->map( \&get_title );
sub get_title{my( $session, $ds, $eprint ) = @_;print $eprint->get_value( “title” );
}
Data Collections: Search Example
Find eprints in live archive published after 2000
$search = new Search( dataset=>$ds );
Data Collections: Search Example
Find eprints in live archive published after 2000
$search = new Search( dataset=>$ds );
$search->add_field(
$ds->get_field( “date” ),
“2000-” );
Data Collections: Search Example
Find eprints in live archive published after 2000
$search = new Search( dataset=>$ds );
$search->add_field(
$ds->get_field( “date” ),
“2000-” );
$results = $search->perform_search;
Data Collections: Search Example
Find eprints in live archive published after 2000
$search = new Search( dataset=>$ds );
$search->add_field(
$ds->get_field( “date” ),
“2000-” );
$results = $search->perform_search;
$results->map( ... );
API Essentials: Further Reading
http://software.eprints.org/training
Walkthrough: ZIP Plugin
Writing Export Plugins
Typically a standalone Perl module in perl_lib/EPrints/Plugin/Export/
2 stage process1. Register export capabilities2. Define conversion
from data object to output format
Export Plugin: Registration
Name of plugin What the plugin can convert
type of object (eprint, user) single or object or list of objects (or
both)
Who can use it File extension and MIME type of
output format
Registration Example: BibTeX
$self->{name} = "BibTeX";
$self->{accept} = [ 'list/eprint', 'dataobj/eprint' ];
$self->{visible} = "all";
$self->{suffix} = ".bib";
$self->{mimetype} = "text/plain";
Converts lists or single EPrint objects Available to all users Produces plain text file with .bib extension
Registration Example: FOAF
$self->{name} = "FOAF Export";
$self->{accept} = [ 'dataobj/user' ];
$self->{visible} = "all";
$self->{suffix} = ".rdf";
$self->{mimetype} = "text/xml";
Converts single User objects Available to all users Produces XML file with .rdf extension
Registration Example: XML
$self->{name} = "EP3 XML";
$self->{accept} = [ 'list/*', 'dataobj/*' ];
$self->{visible} = "all";
$self->{suffix} = ".xml";
$self->{mimetype} = "text/xml";
Converts any data object Available to all users Produces XML file with .xml extension
Export Plugin: Conversion
1. map data object(s) to output format2. serialise the output format Mapping example: EndNote
$data->{K} = $dataobj->get_value( "keywords" );
$data->{T} = $dataobj->get_value( "title" );
$data->{U} = $dataobj->get_url;
Export Plugin: Template
1. Register Subclass
EPrints::Plugin::Export tells EPrints this is an export plugin inherits all export plugin mechanics could subclass existing plugin e.g.
XML, Feed
Define name, accept, visible etc. in constructor of plugin module
Export Plugin: Template (2)
2. Conversion If plugin can process lists
(optionally) define output_list function
otherwise output_dataobj called for every data object in the list
If plugin can process single data objects define output_dataobj function convert a single data object
Export Plugin: Walkthrough
Zip export Bundle all documents into single zip
e.g for downloading search results to desktop
Use 3rd party library to create zip file Archive::Zip by Adam Kennedy several other Perl modules for zip easy to download and install from CPAN
Zip Export: Getting Started
Create a file for plugin perl_lib/EPrints/Plugin/Export/Zip.pm
Tell EPrints this is an export plugin
package EPrints::Plugin::Export::Zip;
@ISA = ('EPrints::Plugin::Export');
use Archive::Zip;
Zip Export: Registration
Register plugin capabilities in constructor
sub new{my ($class, %opts) = @_;my $self = $class->SUPER::new(%opts);$self->{name} = 'Zip';$self->{accept} = [ 'list/eprint' ];$self->{visible} = 'all';$self->{suffix} = '.zip';$self->{mimetype} = 'application/zip‘return $self;
}
Zip Export: Conversion
Define output_list function Passed list of eprints to convert Create new zip archive and iterate over list
sub output_list{my ( $plugin, %opts ) = @_;my $list = $opts{list};
Zip Export: Conversion
Define output_list function Passed list of eprints to convert Create new zip archive and iterate over list
sub output_list{my ( $plugin, %opts ) = @_;my $list = $opts{list};my $zip = Archive::Zip->new;
Zip Export: Conversion
Define output_list function Passed list of eprints to convert Create new zip archive and iterate over list
sub output_list{my ( $plugin, %opts ) = @_;my $list = $opts{list};my $zip = Archive::Zip->new;foreach my $eprint ($list->get_records){
...}
Zip Export: Conversion (2)
For each document, add all files to zip Top level directory keeps things tidy when
unzipped Organise files inside zip using directories
my $eprintid = $eprint->get_id;foreach my $doc ($eprint->get_all_documents){
}
Zip Export: Conversion (2)
For each document, add all files to zip Top level directory keeps things tidy when
unzipped Organise files inside zip using directories
my $eprintid = $eprint->get_id;foreach my $doc ($eprint->get_all_documents){my $path = $doc->local_path;
}
Zip Export: Conversion (2)
For each document, add all files to zip Top level directory keeps things tidy when
unzipped Organise files inside zip using directories
my $eprintid = $eprint->get_id;foreach my $doc ($eprint->get_all_documents){my $path = $doc->local_path;my $docpos = $doc->get_value( "pos" );$zip->addTree(
$path,"export/$eprintid/$docpos");
}
Zip Export: Conversion (3)
Serialise to filehandle or string
if( defined $opts{fh} ){$zip->writeToFileHandle($opts{fh},'zip' );return undef;
}
Zip Export: Conversion (3)
Serialise to filehandle or string
if( defined $opts{fh} ){$zip->writeToFileHandle($opts{fh},'zip' );return undef;
}
my $archive = '';open( my $FH, '>', \$archive );$zip->writeToFileHandle( $FH, 'zip' );return $archive;
Zip Export: Testing
Appears on search results screen
Downloads zip file to desktop
Zip Export: Testing
top level folder
Zip Export: Testing
folder for each eprint
Zip Export: Testing
folder for each document
Zip Export: Testing
document files
Zip Export: Simple Improvements
Include HTML index file lists citations, link to documents see Tom Healy’s walkthrough
Better directory names include date in top level directory
name use eprint title rather than ID?
Zip Export: Simple Improvements (2)
Scalability get_records loads all eprints at once map is more efficient
Better “housekeeping” check Archive::Zip available hide plugin if not see Tom Healy’s walkthrough
Zip Export: Sharing
Share Zip.pm with community via http://files.eprints.org/
Drop-in install for other repositories
Walkthrough: Formats Screen
Writing Screen Plugins
One or more Perl modules in perl_lib/EPrints/Plugin/Screen/ often bundled with phrases,
configuration files, stylesheets etc.
2 stage process1. Register2. Define functionality
Screen Plugin: Registration
Actions plugin can carry out (if any) Where plugin and/or actions will
appear named placeholder (list) position in list will be displayed as link, button, icon or
tab
Who can use plugin
Registration Example: Manage Deposits
$self->{appears} = [ { place => "key_tools", position => 100, }];
key_tools list
Registration Example: EPrint Details
eprint_view_tabs list (each tab is a single
screen plugin)
$self->{appears} = [ { place => "eprint_view_tabs", position => 100, },];
Registration Example: New Item
item_tools list (create action will be invoked when button
pressed)
$self->{appears} = [ { place => “item_tools", position => 100, action => “create”, },];
Screen Plugin: Define Functionality
3 types of screen plugin1. Render only
define how to produce output page
2. Action only no output page define how to carry out action(s)
Screen Plugin: Define Functionality
3. Combined (interactive) define how to produce output page define how to carry out action(s)
Screen Plugin Template: Render Only
1. Register Subclass EPrints::Plugin::Screen
tells EPrints this is a screen plugin inherits all screen plugin mechanics could subclass existing plugin e.g. EPrint,
User Define where plugin appears Define who can view plugin (if
required) can_be_viewed function
Screen Plugin Template: Render Only (2)
2. Define functionality Define render function Produces output page
Screen Plugin Template: Action Only
1. Register Define actions supported Define where actions appear Define who can use actions
allow_ACTION function for each action
Screen Plugin Template: Action Only (2)
2. Define functionality Define action_ACTION function for
each action carries out the action use add_message to show result or
error redirect to a different screen when
done
Screen Plugin Template: Combined
Combine templates render displays link/buttons which
invoke actions Example: Delete EPrint screen
registers remove and cancel actions render function displays Are you sure?
screen with OK/Cancel buttons OK/Cancel buttons invoke remove/cancel actions
Screen Plugin: Walkthrough
Report screen Render only Summary of document formats
How many of each document format are there in the repository
For editors and administrators only
Formats Screen: Getting Started
Create a file for plugin perl_lib/EPrints/Plugin/Screen/Formats.pm
Tell EPrints this is a Screen plugin
package EPrints::Plugin::Screen::DocTypes;
@ISA = ( 'EPrints::Plugin::Screen' );
Formats Screen: Registration
Add to list of plugins on Admin screensub new
{
my( $class, %params ) = @_;
my $self = $class->SUPER::new(%params);
$self->{appears} = [
{ place => "admin_actions",
position => 1000, },
];
return $self;
}
Formats Screen: Authorisation
Restrict access Only editors and admins have the
status privilege
sub can_be_viewed
{
my( $self ) = @_;
return $self->allow( "status" );
}
Formats Screen: Output Page
Generate output page First get the archive dataset...
sub render
{
my( $self ) = @_;
my $session = $self->{session};
my $ds = $session->get_repository
->get_dataset( "archive" );
Formats Screen: Output Page (2)
...then use map to iterate over dataset Keep count of document formats
my %counts = ();$ds->map( $session, sub {my( $session, $ds, $eprint, $counts ) = @_;
}, \%counts );
Formats Screen: Output Page (2)
...then use map to iterate over dataset Keep count of document formats
my %counts = ();$ds->map( $session, sub {my( $session, $ds, $eprint, $counts ) = @_;foreach my $doc ($eprint->get_all_documents){
}}, \%counts );
Formats Screen: Output Page (2)
...then use map to iterate over dataset Keep count of document formats
my %counts = ();$ds->map( $session, sub {my( $session, $ds, $eprint, $counts ) = @_;foreach my $doc ($eprint->get_all_documents){
$counts->{$doc->get_type}++;}
}, \%counts );
Formats Screen: Output Page (3)
Now ready to display something Start by creating a table to hold the
results
my $html = $session->make_doc_fragment;
my $table = $session->make_element( "table", border => 0 );
$html->appendChild( $table );
Formats Screen: Output Page (4)
Add the document formats and totals to the table
foreach my $type ( keys %counts ){
}return $html;
Formats Screen: Output Page (4)
Add the document formats and totals to the table
foreach my $type ( keys %counts ){$table->appendChild(
$session->render_row($session->html_phrase(
"document_typename_$type" ),$session->make_text(
$counts{$type} ) ) );}return $html;
Formats Screen: Testing
Formats screen appears on list of admin tools
Formats Screen: Testing
Formats screen output
page
Format Screen: Simple Improvements
Count document formats in other datasets
inbox, buffer, deletion
..or whole repository eprint dataset
Report zero counts Better output display
simple bar chart
Formats Screen: Sharing
2 files Formats.pm Small phrases file
formats.xml phrases to use for title and description
Share with community via http://files.eprints.org/
Summary of Talk
Walked through 2 useful plugins Minimal coding
both ~50 lines of (well formatted) code
Minimal learning curve API essentials plugin templates
Minimal hassle easy to share easy to install
OR08 Training Resources
Live CD Plugin exercises
http://software.eprints.org/training/
Plugin walkthroughs http://wiki.eprints.org/w/Contribute
:_Plugins
Community contributed plugins http://files.eprints.org/view/type/plugin.
html
EPrints Experts
top related