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.

To do this we need to add an input form to our render method, this is a standard HTML input form. This needs to be added ABOVE the call to action_process_eprint!

Firstly lets make a form and append it to the output ($ret):

 my $form = $repository->render_form("POST");
 $ret->appendChild( $form );

Next lets add an input field to hold the value the user types in and append this to the form:

 my $input_field = $repository->make_element(
                     "input",
                     name=> "input_field",
                     type=> "text"
                     );
 $form->appendChild($input_field);
 

Then append a button which the user can press, note that a button is tied to an action on a screen, thus you can redirect people around eprints in this way to perform quiet complex actions.

 my $submit_button = $screen->render_action_button(
                       {
                       action => "process_input",
                       screen => $screen,
                       screen_id => $screen_id,
                       } );
 

NOTE: This button requires the $screen and $screen_id parameters to be set. So somewhere earlier in the render method you need to add the following two lines:

 my $screen_id = "Screen::".$self->{processor}->{screenid};
 my $screen = $repository->plugin( $screen_id, processor => $self->{processor} );

Lastly in the render method we need to CHANGE the processing code added previously to handle both ways of handing the screen an eprint_id.

To do this, find the previously added $self->action_process_input() line and change this to the following:

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

 if ((!defined $eprint) and (defined $input_value)) {
         $self->action_process_input();
 }

Doing this will cause the input_field box which is POSTED from our form to be the primary source of eprint_id. However if there is no POST value, the render method will attempt to get the value passed in the URL.

Lastly we need to enable the action that the button is calling but registering it as an action on the screen. To do this add the following line to the Plug-ins new method:

 $self->{actions} = [qw/ process_input /];

Actions also hold permissions that define which types of user can perform this action, in this case we are going to let everyone perform the action within this screen. The following method (which needs to be added below the can_be_viewed method) handles this. It is required!

 sub allow_process_input
 {
       my ( $self ) = @_;
 
       return 1;
 }

Rendering a citation and Making a new Citation

Rendering a Citation

This is very simple, try changing the part in the render method where we fetch the title and append it to the following line only:

 $ret->appendChild($eprint->render_citation("default"));

This will append the default citation for this EPrint to the screen.

Making a New Citation (Optional)

EPrint citations are defined as XML and stored in the cfg/citations/eprint/ directory (from the archive_name directory).

You can simple copy one of the provided ones and change it to include different fields or be in a different order, more on this soon.