Difference between revisions of "Contribute: Plugins/ExportPluginsHelloOld"

From EPrints Documentation
Jump to: navigation, search
 
(38 intermediate revisions by 2 users not shown)
Line 1: Line 1:
= Export Plugin Tutorial 1: Hello, World! =
+
[[Category:Contribute]]
 +
[[Category:Plugins]]
  
On this page you will learn how to create a simple export plugin for EPrints, which will generate a list of titles from the results of a search. A basic knowledge of Perl is needed, but the code will be explained nearly line by line.
+
= Export Plugin Tutorial 1: "Hello, World!" =
  
== Before You Start ==
+
In this tutorial you will learn how to create a simple export plugin for EPrints, which will generate a list of titles from the results of a search. A basic knowledge of Perl is needed, but the code will be explained fully.
  
It is sensible to separate the plugins you create for EPrints from those included with it. Create a directory for your export plugins in the main plugin directory (usually /opt/eprints3/perl_lib/EPrints/Plugin/Export) for example /opt/eprints3/perl_lib/EPrints/Plugin/Export/Foo.
+
= Before You Start =
  
== HelloExport.pm ==
+
Create a directory for your export plugins in the local repository cfg directory, <EPrints_root>/archives/<archive_name>cfg/plugins/EPrints/Plugin/Export. Note archvies/<archive_name>cfg/plugins/ is a special directory which is added to the perl path when your webserver starts. Then in the directory create a directory for your plugins. The directory used for these examples is called "MyPlugins".
  
Replace Foo with the name of the directory you have decided to put your export plugins in and place the code below in a file called HelloExport.pm in that directory.
+
= HelloExport.pm =
 +
 
 +
Now place the code below in a file called HelloExport.pm in that directory.
  
 
<pre>
 
<pre>
package EPrints::Plugin::Export::Foo::HelloExport;
+
package EPrints::Plugin::Export::MyPlugins::HelloExport;
  
@ISA = ("EPrints::Plugin::Export");
+
@ISA = ('EPrints::Plugin::Export');
  
 
use strict;
 
use strict;
Line 24: Line 27:
 
         my $self = $class->SUPER::new(%opts);
 
         my $self = $class->SUPER::new(%opts);
  
         $self->{name} = "Hello, World!";
+
         $self->{name} = 'Hello, World!';
 
         $self->{accept} = [ 'dataobj/eprint', 'list/eprint' ];
 
         $self->{accept} = [ 'dataobj/eprint', 'list/eprint' ];
         $self->{visible} = "all";
+
         $self->{visible} = 'all';
         $self->{suffix} = ".txt";
+
         $self->{suffix} = '.txt';
         $self->{mimetype} = "text/plain; charset=utf-8";
+
         $self->{mimetype} = 'text/plain; charset=utf-8';
  
 
         return $self;
 
         return $self;
Line 37: Line 40:
 
         my ($plugin, $dataobj) = @_;
 
         my ($plugin, $dataobj) = @_;
  
         return $dataobj->get_value("title")."\n";
+
         return $dataobj->value('title')."\n";
 
}
 
}
  
Line 44: Line 47:
 
</pre>
 
</pre>
  
== Testing Your Plugin ==
 
  
== In More Detail ==
+
= In More Detail =
 +
 
 +
== Housekeeping ==
 
<pre>
 
<pre>
 
package EPrints::Plugin::Export::Foo::HelloExport;
 
package EPrints::Plugin::Export::Foo::HelloExport;
Line 52: Line 56:
 
Export plugins need to inherit from the EPrints::Plugin::Export class.
 
Export plugins need to inherit from the EPrints::Plugin::Export class.
 
<pre>
 
<pre>
@ISA = ("EPrints::Plugin::Export");
+
@ISA = ('EPrints::Plugin::Export');
 
</pre>
 
</pre>
  
The Constructor for our Plugin. After the implicit class reference, a hash of options is given.
+
== Constructor ==
 +
After the implicit class reference, a hash of options is given.
 
<pre>
 
<pre>
sub new
 
{
 
 
         my ($class, %opts) = @_;
 
         my ($class, %opts) = @_;
 
</pre>
 
</pre>
 +
 
We create a new export plugin by calling the Eprints::Plugin::Export constructor
 
We create a new export plugin by calling the Eprints::Plugin::Export constructor
 
<pre>
 
<pre>
Line 69: Line 73:
 
This is the name that will appear in the export dropdown menu. The name should therefore be short and descriptive.
 
This is the name that will appear in the export dropdown menu. The name should therefore be short and descriptive.
 
<pre>
 
<pre>
         $self->{name} = "Hello, World!";
+
         $self->{name} = 'Hello, World!';
 
</pre>
 
</pre>
The accept field is set to an array containing the type of objects this
+
 
 +
The accept field is a list containing the types of objects this
 
plugin can deal with. In this case lists of eprints and individual
 
plugin can deal with. In this case lists of eprints and individual
 
eprints.
 
eprints.
Line 77: Line 82:
 
         $self->{accept} = [ 'dataobj/eprint', 'list/eprint' ];
 
         $self->{accept} = [ 'dataobj/eprint', 'list/eprint' ];
 
</pre>
 
</pre>
The visible field denoes the class of user which will be able to see the plugin.
+
The visible field denotes the class of user which will be able to see the plugin.
For most export plugins the value "all" will be required, allowing
+
For most export plugins the value 'all' will be required, allowing
all users to see and use the plugin. A value of "staff" would
+
all users to see and use the plugin. A value of 'staff' would
make the plugin only visible to repository staff.
+
make the plugin visible only to repository staff.
 
<pre>
 
<pre>
         $self->{visible} = "all";
+
         $self->{visible} = 'all';
 
</pre>
 
</pre>
 
The suffix field contains the extension of files exported by the plugin.
 
The suffix field contains the extension of files exported by the plugin.
  
The mimetype field defines the MIME type of the files exported by the plugin
+
The mimetype field defines the [http://en.wikipedia.org/wiki/MIME MIME] type of the files exported by the plugin
You can also specify file encoding, for example "text/plain; charset=utf-8" to specify plain text, encoded using utf-8.
+
You can also specify file encoding, for example 'text/plain; charset=utf-8' to specify plain text, encoded using UTF-8.[http://en.wikipedia.org/wiki/UTF-8 UTF-8] is a Unicode character encoding capable of expressing characters from a large number of character sets and so is usually preferable to [http://en.wikipedia.org/wiki/ASCII ASCII]
 
<pre>
 
<pre>
         $self->{suffix} = ".txt";
+
         $self->{suffix} = '.txt';
         $self->{mimetype} = "text/plain; charset=utf-8";
+
         $self->{mimetype} = 'text/plain; charset=utf-8';
 
</pre>
 
</pre>
 +
 
We then return our plugin reference.
 
We then return our plugin reference.
 
<pre>
 
<pre>
 
         return $self;
 
         return $self;
}
 
 
</pre>
 
</pre>
This subroutine handles the export of each DataObj.
+
 
Besides a reference to the plugin object, this subroutine is also provided with a reference to an individual DataObj
+
== Processing DataObjs ==
 +
 
 +
This method handles the export of each DataObj. DataObjs make up most of the content of an EPrint repository. The three main types are EPrint defining individual eprints, Document defining collections of one or more files belonging to an EPrints, and User which defines users of the repository.
 +
 
 +
Besides an implicit reference to the Plugin object, this method is also provided with a reference to an individual DataObj. It is called by several [http://en.wikipedia.org/wiki/Common_Gateway_Interface CGI] and command line scripts to export single DataObjs, for instance the item control screen for repository staff. It is also called by the list handling method on each DataObj in a list, for example the results of a search. That will be explained in [[Contribute:_Plugins/ExportPluginsList|the next tutorial]].
 +
 
 +
In the example below we get the title of each DataObj, but there are large number of fields which you can extract from each DataObj. For example try changing "title" to "abstract" to print the abstract of each eprint.
 +
 
 
<pre>
 
<pre>
 
sub output_dataobj
 
sub output_dataobj
Line 105: Line 117:
  
 
         # Return a scalar containing the title.
 
         # Return a scalar containing the title.
         return $dataobj->get_value("title")."\n";
+
         return $dataobj->value('title')."\n";
 
}
 
}
 
</pre>
 
</pre>
  
Standard Perl package fayre.
+
== Finishing Off ==
 +
 
 +
Standard Perl package requirement.
 
<pre>
 
<pre>
 
1;
 
1;
  
 
</pre>
 
</pre>
 +
 +
= Testing Your Plugin =
 +
Remember you must always '''restart your web server''' when you change perl code in EPrints to reload the perl. Alternatively you can call bin/epadmin reload <archive_id>.
 +
 +
Now  perform a search.
 +
 +
If all is well your plugin should appear in the dropdown menu. Select it and click export. As long as the search provided some results, you should get a list of EPrint titles returned.
 +
 +
== Sample Output ==
 +
[[Image:Exphello.png]]

Latest revision as of 16:11, 24 February 2010


Export Plugin Tutorial 1: "Hello, World!"

In this tutorial you will learn how to create a simple export plugin for EPrints, which will generate a list of titles from the results of a search. A basic knowledge of Perl is needed, but the code will be explained fully.

Before You Start

Create a directory for your export plugins in the local repository cfg directory, <EPrints_root>/archives/<archive_name>cfg/plugins/EPrints/Plugin/Export. Note archvies/<archive_name>cfg/plugins/ is a special directory which is added to the perl path when your webserver starts. Then in the directory create a directory for your plugins. The directory used for these examples is called "MyPlugins".

HelloExport.pm

Now place the code below in a file called HelloExport.pm in that directory.

package EPrints::Plugin::Export::MyPlugins::HelloExport;

@ISA = ('EPrints::Plugin::Export');

use strict;

sub new
{
        my ($class, %opts) = @_;

        my $self = $class->SUPER::new(%opts);

        $self->{name} = 'Hello, World!';
        $self->{accept} = [ 'dataobj/eprint', 'list/eprint' ];
        $self->{visible} = 'all';
        $self->{suffix} = '.txt';
        $self->{mimetype} = 'text/plain; charset=utf-8';

        return $self;
}

sub output_dataobj
{
        my ($plugin, $dataobj) = @_;

        return $dataobj->value('title')."\n";
}

1;


In More Detail

Housekeeping

package EPrints::Plugin::Export::Foo::HelloExport;

Export plugins need to inherit from the EPrints::Plugin::Export class.

@ISA = ('EPrints::Plugin::Export');

Constructor

After the implicit class reference, a hash of options is given.

        my ($class, %opts) = @_;

We create a new export plugin by calling the Eprints::Plugin::Export constructor

        my $self = $class->SUPER::new(%opts);

Now we set a number of fields to register our new plugin.

This is the name that will appear in the export dropdown menu. The name should therefore be short and descriptive.

        $self->{name} = 'Hello, World!';

The accept field is a list containing the types of objects this plugin can deal with. In this case lists of eprints and individual eprints.

        $self->{accept} = [ 'dataobj/eprint', 'list/eprint' ];

The visible field denotes the class of user which will be able to see the plugin. For most export plugins the value 'all' will be required, allowing all users to see and use the plugin. A value of 'staff' would make the plugin visible only to repository staff.

        $self->{visible} = 'all';

The suffix field contains the extension of files exported by the plugin.

The mimetype field defines the MIME type of the files exported by the plugin You can also specify file encoding, for example 'text/plain; charset=utf-8' to specify plain text, encoded using UTF-8.UTF-8 is a Unicode character encoding capable of expressing characters from a large number of character sets and so is usually preferable to ASCII

        $self->{suffix} = '.txt';
        $self->{mimetype} = 'text/plain; charset=utf-8';

We then return our plugin reference.

        return $self;

Processing DataObjs

This method handles the export of each DataObj. DataObjs make up most of the content of an EPrint repository. The three main types are EPrint defining individual eprints, Document defining collections of one or more files belonging to an EPrints, and User which defines users of the repository.

Besides an implicit reference to the Plugin object, this method is also provided with a reference to an individual DataObj. It is called by several CGI and command line scripts to export single DataObjs, for instance the item control screen for repository staff. It is also called by the list handling method on each DataObj in a list, for example the results of a search. That will be explained in the next tutorial.

In the example below we get the title of each DataObj, but there are large number of fields which you can extract from each DataObj. For example try changing "title" to "abstract" to print the abstract of each eprint.

sub output_dataobj
{
        my ($plugin, $dataobj) = @_;

        # Return a scalar containing the title.
        return $dataobj->value('title')."\n";
}

Finishing Off

Standard Perl package requirement.

1;

Testing Your Plugin

Remember you must always restart your web server when you change perl code in EPrints to reload the perl. Alternatively you can call bin/epadmin reload <archive_id>.

Now perform a search.

If all is well your plugin should appear in the dropdown menu. Select it and click export. As long as the search provided some results, you should get a list of EPrint titles returned.

Sample Output

Exphello.png