View source for Using the new API

[[Category:EPrints Bazaar]]
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: $eprint_id")
                                );
        }
  
  }

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.

=Doing a search and mapping a list (Harder)=

Taking our existing plug-in we now want to make our input box a search term "Observations" and print out a list of EPrints.

To do this we need to modify our action_process_input method and the render method from before. 

==Searching==

First things first we need a place to store a list of eprints rather than just one. Let's declare (or change the existing) global variable eprints:

  our $eprints = undef;

Next lets change the action_process_input method to perform a search, to do this find the line which reads the "input_field" parameter and change this:

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

As this no longer represents an EPrint ID we'll rename the parameter. 

You can delete all the lines after this in the action_process_input method as we are going to replace them all.

Next lets get the eprint dataset so we can search it:

  my $eprint_dataset = $repository->dataset( "eprint" );

Now we are going to search on TITLE so lets define the filter for the search. Here we are doing a fuzzy search (the match => EX parameter is not used). 

  my @filters = (
                { meta_fields => [qw( title )], value => $input_value },
                );

Now lets do the search and assign the output to our list of eprints:

   $eprints = $eprint_dataset->search(
                        filters => \@filters,
                        custom_order=>"-datestamp",
                        limit => 10,
                        );

Notice that we are setting an order (based upon age) for the eprints to be listed in. Also we are limiting the number returned to 10. 

Finally lets do some error handling if the list is empty and nothing was found. This is just a little more detailed than before. 

  if (!defined $eprints or $eprints->count < 1)
        {
                $self->{processor}->add_message(
                                "error",
                                $self->{repository}->make_text("No EPrints found to match search: $input_value")
                                );
        }
  

==Rendering the output==

Lastly to display all the items in our list we need to change the render method.

To do this find the place where did the rendering before (it was inside an "if" statement). 

To perform a bit more error checking lets firstly change the "if" statement slightly:

  if (defined $eprints and $eprints->count > 0)

This will check there is actually something in the list as well as it being defined. 

Next we need to iterate of the items in the list and print their citations.

This can be done using the following map function:

   $eprints->map( sub {
             my( undef, undef, $eprint ) = @_;
   
             $ret->appendChild($eprint->render_citation("default"));
             $ret->appendChild($repository->make_element("br"));
   });

Here we can see that each item in the list is an eprint and we can simply render a citation for each followed by a newline.

==Extension exercise==

* Add a new parameter to allow the user to set a custom limit to the number of results which come back as a result of a search. 
* Tidy up your style
* Define all the missing phrases