Using the new API

The new EPrints API is exposes the basic functionality of a repository in clean way. The aim of the API is to be simple to use but powerful. Some of the more complex things EPrints can do are deliberately not exposed. Our aim is that the EPrints API will remain consistent between versions of the software so your plugins wont break when you upgrade eprints.

This exercise assumes that you have completed the My_First_Bazaar_Package exercise and will be expanding on the screen plug-in detailed in this exercise.

In this exercise we are going to expand our screen to take a parameter and process it. We shall use the API to retrieve information from within EPrints an display it on screen.

Retrieving an object by ID

Reading EPrint ID from Address Bar Parameter

In order to do this we are going to create some special action methods, these can perform operations when requested.

Taking the screen plug-in developed in the My_First_Bazaar_Package exercise, firstly add a global screen variable which we can store an eprint object inside.

 our $eprint = undef;

This will be used later.

Next we want to define a couple of new methods, the first of which reads a parameter "input_field":

 my $eprint_id = $repository->param( "input_field" );

and then retrieves the eprint corresponding to the value set by the parameter:

 $eprint = $repository->eprint( $eprint_id );

In order to call these methods at the appropriate time lets add a whole method to our screen plug-in. Add the following near the top of the file:

 sub action_process_input {
 
       my ( $self ) = @_;
 
       my $repository = $self->{repository};
 
       my $eprint_id = $repository->param( "input_field" );
 
       ## DO SOME VALIDATION HERE MAYBE???
 
       $eprint = $repository->eprint( $eprint_id );
 
       if (!defined $eprint)
       {
               $self->{processor}->add_message(
                               "error",
                               $self->{repository}->make_text("No EPrint found with ID: $input_value")
                               );
       }
 
 }

At this point we can call this method from our existing render method to get a handle on the eprint object.

To do this add the following to the bottom of the existing render method:

 $self->action_process_input();

You could make the action_process_input method return the eprint rather than set it as a global, however the reason to not do this will become apparent later.

Lastly, lets get the title of the EPrint an print it out.

Again add the following to the bottom of our render method:

 if (defined $eprint) {
               my $title = $eprint->get_value("title");
 
               my $h1 = $repository->make_element("h1");
               $h1->appendChild($repository->make_text($title));
      
               $ret->appendChild($h1);
 }

At this point you should be able to save and package your bazaar package (or just test it in line).

To test it point your web browser at the screen plug-in (by clicking it in the interface) and add a &input_field=X parameter to the end of the URL in the address bar. CHANGE X to a number which might be the id number of an EPrint.

Reading EPrintID from input field

This is an extension of the previous exercise, it does not work without it.