Using the new API - Revision history

Alan.stiles@open.ac.uk at 11:11, 24 January 2013

2013-01-24T11:11:49Z

← Older revision		Revision as of 11:11, 24 January 2013
Line 1:		Line 1:
	[[Category:EPrints Bazaar]]		[[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.		The new EPrints API 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.		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.

DaveTarrant at 12:29, 20 July 2011

2011-07-20T12:29:58Z

DaveTarrant: /* Reading EPrintID from input field */

2011-03-30T14:10:14Z

Reading EPrintID from input field

← Older revision		Revision as of 14:10, 30 March 2011
Line 84:		Line 84:

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

	Next lets add an input field to hold the value the user types in and append this to the form:		Next lets add an input field to hold the value the user types in and append this to the form (between the lines above):

	my $input_field = $repository->make_element(		my $input_field = $repository->make_element(
Line 103:		Line 104:
	screen_id => $screen_id,		screen_id => $screen_id,
	} );		} );
			$form->appendChild($submit_button);

William.nixon@glasgow.ac.uk: /* Reading EPrintID from input field */

2011-03-30T13:13:17Z

Reading EPrintID from input field

← Older revision		Revision as of 13:13, 30 March 2011
Line 79:		Line 79:
	This is an extension of the previous exercise, it does not work without it.		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~~!		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_input!

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

William.nixon@glasgow.ac.uk: /* Reading EPrint ID from Address Bar Parameter */

2011-03-30T13:12:29Z

Reading EPrint ID from Address Bar Parameter

← Older revision		Revision as of 13:12, 30 March 2011
Line 44:		Line 44:
	$self->{processor}->add_message(		$self->{processor}->add_message(
	"error",		"error",
	$self->{repository}->make_text("No EPrint found with ID: $~~input_value~~")		$self->{repository}->make_text("No EPrint found with ID: $eprint_id")
	);		);
	}		}
Line 73:		Line 73:
	At this point you should be able to save and package your bazaar package (or just test it in line).		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.		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==		==Reading EPrintID from input field==

DaveTarrant: /* Doing a search and mapping a list */

2011-03-29T15:44:22Z

Doing a search and mapping a list

← Older revision		Revision as of 15:44, 29 March 2011
Line 151:		Line 151:
	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.		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=		=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

DaveTarrant: /* Making a citation (optional) */

2011-03-29T15:13:48Z

Making a citation (optional)

← Older revision		Revision as of 15:13, 29 March 2011
Line 135:		Line 135:
	}		}

	=Making a ~~citation (optional)~~=		=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=		=Doing a search and mapping a list=

DaveTarrant: /* Reading EPrintID from input field */

2011-03-29T15:05:35Z

Reading EPrintID from input field

← Older revision		Revision as of 15:05, 29 March 2011
Line 126:		Line 126:
	$self->{actions} = [qw/ process_input /];		$self->{actions} = [qw/ process_input /];

	Actions also hold permissions ~~which defines~~ 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!		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		sub allow_process_input
Line 134:		Line 134:
	return 1;		return 1;
	}		}


	=Making a citation (optional)=		=Making a citation (optional)=

DaveTarrant at 15:05, 29 March 2011

2011-03-29T15:05:08Z

← Older revision		Revision as of 15:05, 29 March 2011
Line 79:		Line 79:
	This is an extension of the previous exercise, it does not work without it.		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 which defines 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;
			}

DaveTarrant at 14:45, 29 March 2011

2011-03-29T14:45:56Z

@@ Line 1: / Line 1: @@
 [[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
+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.
-==Retrieving an object by ID==
+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.
-==Making a citation (optional)==
+==Reading EPrint ID from Address Bar Parameter==
-==Doing a search and mapping a list==
+This will be used later.

← Older revision		Revision as of 12:29, 20 July 2011
Line 68:		Line 68:
	$h1->appendChild($repository->make_text($title));		$h1->appendChild($repository->make_text($title));

	$~~ret~~->appendChild($h1);		$frag->appendChild($h1);
	}		}

Line 81:		Line 81:
	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_input!		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_input!

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

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

	Next lets add an input field to hold the value the user types in and append this to the form (between the lines above):		Next lets add an input field to hold the value the user types in and append this to the form (between the lines above):
Line 143:		Line 143:
	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:		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"));		$frag->appendChild($eprint->render_citation("default"));

	This will append the default citation for this EPrint to the screen.		This will append the default citation for this EPrint to the screen.
Line 223:		Line 223:
	my( undef, undef, $eprint ) = @_;		my( undef, undef, $eprint ) = @_;

	$~~ret~~->appendChild($eprint->render_citation("default"));		$frag->appendChild($eprint->render_citation("default"));
	$~~ret~~->appendChild($repository->make_element("br"));		$frag->appendChild($repository->make_element("br"));
	});		});