easy extensions for eprints

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 );





print $eprint->get_value( “title” );





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






$doc->set_value( “license”,

“cc_public_domain” );





$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” );




$ds->map( $session, \&get_title );




$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 );




$search->add_field(

$ds->get_field( “date” ),

“2000-” );




$search->add_field(


“2000-” );

$results = $search->perform_search;




$search->add_field(


“2000-” );

$results = $search->perform_search;

$results->map( ... );

API Essentials: Further Reading

http://software.eprints.org/training

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->{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->{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};



sub output_list{my ( $plugin, %opts ) = @_;my $list = $opts{list};my $zip = Archive::Zip->new;



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){

}




my $eprintid = $eprint->get_id;foreach my $doc ($eprint->get_all_documents){my $path = $doc->local_path;

}




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");

}


Serialise to filehandle or string

if( defined $opts{fh} ){$zip->writeToFileHandle($opts{fh},'zip' );return undef;

}


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

http://files.eprints.org/


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 );



my %counts = ();$ds->map( $session, sub {my( $session, $ds, $eprint, $counts ) = @_;foreach my $doc ($eprint->get_all_documents){

}}, \%counts );



my %counts = ();$ds->map( $session, sub {my( $session, $ds, $eprint, $counts ) = @_;foreach my $doc ($eprint->get_all_documents){

$counts->{$doc->get_type}++;}

}, \%counts );


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 );


Add the document formats and totals to the table

foreach my $type ( keys %counts ){

}return $html;


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

http://software.eprints.org/training/

http://wiki.eprints.org/w/Contribute:_Plugins

http://wiki.eprints.org/w/Contribute:_Plugins

http://files.eprints.org/view/type/plugin.html

http://files.eprints.org/view/type/plugin.html

easy extensions for eprints

Documents