My First Bazaar Package

Introduction

In this tutorial we look at how to create a simple Bazaar Package (epm) ready for distribution via the EPrints Bazaar Store.

We are going to create this example simple and create a simple screen plug-in which will simply say hello to the user.

It will read from a config file a variable which it will repeat back to the user.

Remember the steps to create an epm

• Make it work first locally
• Package up a working version with a spec file and icon.
• Install from the "Local Packages" tab in the bazaar to test it.

Exercise

By this point you should have an EPrints Bazaar capable version of EPrints installed and have a repository set up of which you are the admin user.

You should also have a command line (or other method) for accessing and creating files within the repository directory.

In this demo we are assuming that your root directory is always the archive's home folder found at eprints/archives/archive_name (where archive_name is your archive ID)

Step 1 - Decide a Package Name

I'm going to call my package eprints_test_package which I shall use throughout this exercise, let's hope its unique!

To check it is unique, create a eprints_test_package.spec file with the following content:

 package: eprints_test_package
 version: 0.1
 title: Davetaz's First Package
 description: I'll add one later
 creator: Dave Tarrant <davetaz@foo.bar.org>
 icon: icon.png

You will have to find a random small icon you can use as well, a package without one isn't accepted!

We then package up our spec file and icon only into the root level of a zip file in this case called eprints_test_package.epm

Finally using the "Local Packages" tab in the Bazaar screen, upload your package. If you get a green tick back you have a unique name.

NOTE: This process does not secure you the package name! You can't camp on a name! You secure the name by uploading a working version of your package.

Step 2 - Develop your package

In this example we shall make 3 files, a screen, a config file and a phrase file at the following locations:

• cfg/plugins/EPrints/Plugin/Screen/Admin/EPrintsTestScreen.pm
• cfg/cfg.d/eprints_test_package.pl
• cfg/lang/en/phrases/eprints_test_package.xml

In each of these files copy and paste the following:

EPrintsTestScreen.pm

 package EPrints::Plugin::Screen::Admin::EPrintsTestScreen;
 
 @ISA = ( 'EPrints::Plugin::Screen' );
 
 use strict;
 # Make the plug-in
 sub new
 {
       my( $class, %params ) = @_;
 
       my $self = $class->SUPER::new(%params);
 
       # Where the button to access the screen appears if anywhere, and what priority
       $self->{appears} = [
               {
                       place => "admin_actions",
                       position => 1247,
               },
       ];
 
       return $self;
 }
 
 # Can anyone see this screen.
 sub can_be_viewed
 {
       my( $plugin ) = @_;
 
       return 1;
 }
 
 # What to display
 sub render
 {
       my( $self ) = @_;
 
       my $repository = $self->{repository};
 
       my $ret = $repository->make_doc_fragment();
       my $br = $repository->make_element("br");
 
       my $lang_phrase = $self->html_phrase("eprints_test_phrase");
 
       my $text_from_config = $repository->make_text($repository->{config}->{eprints_test_package}->{phrase});
 
       $ret->appendChild($lang_phrase);
       $ret->appendChild($br);
       $ret->appendChild($text_from_config);
 
       return $ret;
 
 }
 
 1;

cfg/cfg.d/eprints_test_package.pl

 $c->{eprints_test_package}->{phrase} = "This is a phrase, but it shouldn't be we are just testing. It could be a version number or some other variable.";

cfg/lang/en/phrases/eprints_test_package.xml

Finally we need some phrases. The title and description phrases are required if you are going to allow access to the screen from one of the admin menus.

 <?xml version="1.0" encoding="utf-8" standalone="no"?>
 <!DOCTYPE phrases SYSTEM "entities.dtd">
 <epp:phrases xmlns="http://www.w3.org/1999/xhtml" xmlns:epp="http://eprints.org/ep3/phrase" xmlns:epc="http://eprints.org/ep3/control">
 
   <epp:phrase id="Plugin/Screen/Admin/EPrintsTestScreen:title">Davetaz's Test Screen</epp:phrase>
   <epp:phrase id="Plugin/Screen/Admin/EPrintsTestScreen:description">I really need a description</epp:phrase>
 
   <epp:phrase id="Plugin/Screen/Admin/EPrintsTestScreen:eprints_test_phrase">This is our test phrase.</epp:phrase>
 
 </epp:phrases>

Step 3 - Does it work locally

You should now have the 3 files in place and if you reload your config (via the "Reload Configuration" button on the "Config. Tools" tab of the admin interface) you should then be able to go to the "Misc. Tools" tab and find your screen. Clicking on it should show our two phrases, one from the phrase file and one from the config listed on 2 different lines.

Step 3b - HELP - It didn't work

If you made an error then the error message will likely be in the web servers error log.

Here is a very useful command for full debugging of EPrints and restarting the web server at the same time.

In a new terminal as root, type and execute the following (on debian based systems):

 apache2ctl restart && tail -f /var/apache2/logs/error_log

This will restart the web server and then give you a live view on the error log.

Attempting to reload your screen again (hit F5) will the cause the error to be displayed instantly in this terminal. It is recommended to leave this terminal open for debugging at all times.

Step 4 - Package it up and test it

Now what we want to do is create a directory for our package (even better an svn or other change management system!) and move the files we just created out of the repository and into a directory which we can build out package from.

So in your home directory (not the eprints one) make a folder for your package and move the files into it including the spec file and icon.

IMPORTANT: The directory structure needs to be preserved thus your directory listing should look as follows:

• icon.png
• eprints_test_package.spec
• cfg/plugins/EPrints/Plugin/Screen/Admin/EPrintsTestScreen.pm
• cfg/cfg.d/eprints_test_package.pl
• cfg/lang/en/phrases/eprints_test_package.xml

Before we package it up we want to update our spec file to point at the configuration file, so in the spec file add the line:

 configuration_file: cfg/cfg.d/eprints_test_package.pl 

With this done, reload the config on your repository to make sure the screen has gone! You can even use view config to make sure all the related files have gone.

Finally package up your directory using zip to make an epm called eprints_test_package.epm as before and upload this via the "Local Packages" tab, you may need to remove the old one first! Also did you version your package from the initial 0.1 marker in the spec file. (Get a script to grab the SVN version to go here when you build a propper package)

With all this done, if you have a green box, click the install button and see if it worked!

If it didn't you will need to remove it (if it installed) and use the steps outlined in 3b to debug why.

Step 4b - I'm stuck in limbo, package won't remove (a.k.a. using epm via the command line)

If you get stuck you can use the command line scripts which allow you to force changes.

You have to be aware that forcing changes means that any errors (prerm and dataset removals etc) will be ignored!

The syntax is as follows (and needs to be executed as the eprints user at the root level of the eprints home directory)

 perl bin/epm archive_name [install|remove] package_name [--force]

This basically replicates the graphically functionality except the addition of the --force flag. Search functionality is still to be added... maybe.

Exercise 2

That the easy exercise done, so how about doing something a little more challenging.

How about using our config file to specify an eprint_id or search expression and then using your screen to display something about this item/list.

For some hints on loading and manipulating EPrints see Manipulating eprints in 3.2.