Easy Extensions for EPrints

1. Easy Extensions for EPrints EPrints Training & Support Session 1 Open Repositories 2008

2. Session 1 Overview • Extending EPrints using plugins • Introduction to plugins • API essentials • Walkthrough: ZIP export • Walkthrough: Formats report • Plugin exercises & EPrints Surgery

3. Introduction to Plugins

4. 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

5. 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...

6. What This Means • Create new repository behaviour • alter, remove or extend plugin suite • Easily share results with community • independent of core

7. 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

8. 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!)

9. 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)

10. API Essentials

11. 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

12. Accessing Data: Example • Get title and pub date of an eprint $eprint = EPrints::DataObj::EPrint ->new( $session, 142 );

13. Accessing Data: Example • Get title and pub date of an eprint $eprint = EPrints::DataObj::EPrint ->new( $session, 142 ); print $eprint->get_value( “title” );

14. 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” ); }

15. Accessing Data: Example (2) • Change the license of a document $doc = EPrints::DataObj::Document ->new( $session, 73 );

16. Accessing Data: Example (2) • Change the license of a document $doc = EPrints::DataObj::Document ->new( $session, 73 ); $doc->set_value( “license”, “cc_public_domain” );

17. 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;

18. 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

19. Data Collections: Datasets • Corresponding dataset for each data object • eprint • document • user • Also datasets of eprints in same state • archive • inbox • buffer • deletion

20. Data Collections: Datasets Example • Get title of every eprint in live archive $ds = $repository ->get_dataset( “archive” );

21. Data Collections: Datasets Example • Get title of every eprint in live archive $ds = $repository ->get_dataset( “archive” ); $ds->map( $session, \&get_title );

22. 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” ); }

23. Data Collections: Search Example • Find eprints in live archive published after 2000 $search = new Search( dataset=>$ds );

24. 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-” );

25. 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;

26. 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( ... );

27. API Essentials: Further Reading • http://software.eprints.org/training

28. Walkthrough: ZIP Plugin

29. Writing Export Plugins • Typically a standalone Perl module in • perl_lib/EPrints/Plugin/Export/ • 2 stage process • Register export capabilities • Define conversion • from data object to output format

30. 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

31. 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

32. 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

33. 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

34. Export Plugin: Conversion • map data object(s) to output format • serialise the output format • Mapping example: EndNote $data->{K} = $dataobj->get_value( "keywords" ); $data->{T} = $dataobj->get_value( "title" ); $data->{U} = $dataobj->get_url;

35. Export Plugin: Template • 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

36. Export Plugin: Template (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

37. 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

38. 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;

39. 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; }

40. 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};

41. 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;

42. 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) { ... }

43. 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) { }

44. 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; }

45. 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"); }

46. Zip Export: Conversion (3) • Serialise to filehandle or string if( defined $opts{fh} ) { $zip->writeToFileHandle($opts{fh},'zip' ); return undef; }

47. 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;

48. Appears on search results screen Downloads zip file to desktop Zip Export: Testing

49. Zip Export: Testing top level folder

50. Zip Export: Testing folder for each eprint