Difference between revisions of "Contribute: Plugins/ExportPluginsList"

From EPrints Documentation
Jump to: navigation, search
(Export Plugin Tutorial 2: Hello, Lists: Copied code down.)
(HelloList.pm)
 
(33 intermediate revisions by 2 users not shown)
Line 1: Line 1:
= Export Plugin Tutorial 2: Hello, Lists =
+
[[Category:Contribute]]
 +
[[Category:Plugins]]
 +
 
 +
= Export Plugin Tutorial 2: List Handling =
 +
 
 +
In this tutorial you will learn to create a slightly more complex export plugin than the one created in [[Contribute:_Plugins/ExportPluginsHello| the previous tutorial]] that changes the way lists of eprints are exported.
 +
 
 +
= HelloList.pm =
 +
The code in the section below should be placed in a file called HelloList.pm in the directory created previously.
  
== HelloList.pm ==
 
 
<pre>
 
<pre>
package EPrints::Plugin::Export::Foo::HelloList;
+
package EPrints::Plugin::Export::MyPlugins::HelloList;
  
@ISA = ("EPrints::Plugin::Export");
+
@ISA = ('EPrints::Plugin::Export');
  
 
use strict;
 
use strict;
Line 15: Line 22:
 
         my $self = $class->SUPER::new(%opts);
 
         my $self = $class->SUPER::new(%opts);
  
         $self->{name} = "Hello, List!";
+
         $self->{name} = 'Hello, List!';
 
         $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 28: Line 35:
 
         my ($plugin, $dataobj) = @_;
 
         my ($plugin, $dataobj) = @_;
  
         return $dataobj->get_id()."\t".$dataobj->get_value("title")."\n";
+
         return $dataobj->get_id()."\t".$dataobj->get_value('title')."\n";
 
}
 
}
  
Line 35: Line 42:
 
         my ($plugin, %opts) = @_;
 
         my ($plugin, %opts) = @_;
  
         my $output = "";
+
         my $r = [];
  
         $output .= "ID\tTitle\n\n";
+
         my $header = "ID\tTitle\n\n";
 +
        if (defined $opts{fh})
 +
        {
 +
                print {$opts{fh}} $header;
 +
        }
 +
        else
 +
        {
 +
                push @{$r}, $header;
 +
        }
  
         foreach my $dataobj ($opts{"list"}->get_records)
+
         foreach my $dataobj ($opts{list}->get_records)
 
         {
 
         {
                 $output .= $plugin->output_dataobj($dataobj, %opts);
+
                 my $part = $plugin->output_dataobj($dataobj, %opts);
 +
                if (defined $opts{fh})
 +
                {
 +
                        print {$opts{fh}} $part;
 +
                }
 +
                else
 +
                {
 +
                        push @{$r}, $part;
 +
                }
 
         }
 
         }
  
         return $output;
+
        if (defined $opts{fh})
 +
        {
 +
                return undef;
 +
        }
 +
         return join('', @{$r});
 
}
 
}
  
Line 50: Line 77:
 
</pre>
 
</pre>
  
== In More Detail ==
+
= In More Detail =
<pre>
+
The above code is very similar to the HelloExport.pm file in [[Contribute:_Plugins/ExportPluginsHello| the previous tutorial]] so only the points where it deviates significantly from that file will be discussed below.
package EPrints::Plugin::Export::Foo::HelloList;
 
  
@ISA = ("EPrints::Plugin::Export");
+
== Housekeeping ==
 +
The package name has been changed to reflect the filename.
  
use strict;
+
<pre>
 +
package EPrints::Plugin::Export::MyPlugins::HelloList;
 +
</pre>
  
sub new
+
== Constructor ==
{
+
Make sure you give each plugin a unique name.
        my ($class, %opts) = @_;
 
  
         my $self = $class->SUPER::new(%opts);
+
<pre>
 +
         $self->{name} = 'Hello, List!';
 +
</pre>
  
        $self->{name} = "Hello, List!";
+
== Dealing With Lists ==
        $self->{accept} = [ 'dataobj/eprint', 'list/eprint' ];
+
In this example the output_list method is overridden in the export plugin to provide column headers. The original method just concatenates the output from the output_dataobj subroutine called on every DataObj in the list.
        $self->{visible} = "all";
 
        $self->{suffix} = ".txt";
 
        $self->{mimetype} = "text/plain; charset=utf-8";
 
  
        return $self;
+
Note that the method is not provided with a bare array of DataObjs, but a List object is provided within the opts hash. To get an array of DataObjs to loop over you must then call that List object's get_record method.
}
 
  
sub output_dataobj
+
== Filehandles ==
{
+
The command line export tool provides the output list method with a filehandle for output in the opts hash, while the [http://en.wikipedia.org/wiki/Common_Gateway_Interface CGI] export uses a value returned from the method. You must deal with the filehandle or you will get no output from the command line tool. In most cases this won't matter, but it is good practice to deal with it.
        my ($plugin, $dataobj) = @_;
 
  
        return $dataobj->get_id()."\t".$dataobj->get_value("title")."\n";
+
The best way to handle output is to check if a filehandle has been provided every time something needs to be output. If a filehandle is provided we print to it, otherwise we save the output for later. At the end of the method we either return undef if a filehandle was provided or we return the saved output otherwise.
}
 
  
 +
<pre>
 
sub output_list
 
sub output_list
 
{
 
{
 
         my ($plugin, %opts) = @_;
 
         my ($plugin, %opts) = @_;
  
         my $output = "";
+
         my $r = [];
  
         $output .= "ID\tTitle\n\n";
+
         my $header = "ID\tTitle\n\n";
 +
        if (defined $opts{fh})
 +
        {
 +
                print {$opts{fh}} $header;
 +
        }
 +
        else
 +
        {
 +
                push @{$r}, $header;
 +
        }
  
         foreach my $dataobj ($opts{"list"}->get_records)
+
         foreach my $dataobj ($opts{list}->get_records)
 
         {
 
         {
                 $output .= $plugin->output_dataobj($dataobj, %opts);
+
                 my $part = $plugin->output_dataobj($dataobj, %opts);
 +
                if (defined $opts{fh})
 +
                {
 +
                        print {$opts{fh}} $part;
 +
                }
 +
                else
 +
                {
 +
                        push @{$r}, $part;
 +
                }
 
         }
 
         }
  
         return $output;
+
        if (defined $opts{fh})
 +
        {
 +
                return undef;
 +
        }
 +
         return join('', @{$r});
 
}
 
}
 +
</pre>
  
1;
+
= Testing Your Plugin =
</pre>
+
 
 +
Restart your webserver and test the plugin as in [[Contribute:_Plugins/ExportPluginsHello| the previous tutorial]].
 +
 
 +
== Sample Output ==
 +
[[Image:Explist.png]]

Latest revision as of 11:59, 12 February 2010


Export Plugin Tutorial 2: List Handling

In this tutorial you will learn to create a slightly more complex export plugin than the one created in the previous tutorial that changes the way lists of eprints are exported.

HelloList.pm

The code in the section below should be placed in a file called HelloList.pm in the directory created previously.

package EPrints::Plugin::Export::MyPlugins::HelloList;

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

use strict;

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

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

        $self->{name} = 'Hello, List!';
        $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->get_id()."\t".$dataobj->get_value('title')."\n";
}

sub output_list
{
        my ($plugin, %opts) = @_;

        my $r = [];

        my $header = "ID\tTitle\n\n";
        if (defined $opts{fh})
        {
                print {$opts{fh}} $header;
        }
        else
        {
                push @{$r}, $header;
        }

        foreach my $dataobj ($opts{list}->get_records)
        {
                my $part = $plugin->output_dataobj($dataobj, %opts);
                if (defined $opts{fh})
                {
                        print {$opts{fh}} $part;
                }
                else
                {
                        push @{$r}, $part;
                }
        }

        if (defined $opts{fh})
        {
                return undef;
        }
        return join('', @{$r});
}

1;

In More Detail

The above code is very similar to the HelloExport.pm file in the previous tutorial so only the points where it deviates significantly from that file will be discussed below.

Housekeeping

The package name has been changed to reflect the filename.

package EPrints::Plugin::Export::MyPlugins::HelloList;

Constructor

Make sure you give each plugin a unique name.

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

Dealing With Lists

In this example the output_list method is overridden in the export plugin to provide column headers. The original method just concatenates the output from the output_dataobj subroutine called on every DataObj in the list.

Note that the method is not provided with a bare array of DataObjs, but a List object is provided within the opts hash. To get an array of DataObjs to loop over you must then call that List object's get_record method.

Filehandles

The command line export tool provides the output list method with a filehandle for output in the opts hash, while the CGI export uses a value returned from the method. You must deal with the filehandle or you will get no output from the command line tool. In most cases this won't matter, but it is good practice to deal with it.

The best way to handle output is to check if a filehandle has been provided every time something needs to be output. If a filehandle is provided we print to it, otherwise we save the output for later. At the end of the method we either return undef if a filehandle was provided or we return the saved output otherwise.

sub output_list
{
        my ($plugin, %opts) = @_;

        my $r = [];

        my $header = "ID\tTitle\n\n";
        if (defined $opts{fh})
        {
                print {$opts{fh}} $header;
        }
        else
        {
                push @{$r}, $header;
        }

        foreach my $dataobj ($opts{list}->get_records)
        {
                my $part = $plugin->output_dataobj($dataobj, %opts);
                if (defined $opts{fh})
                {
                        print {$opts{fh}} $part;
                }
                else
                {
                        push @{$r}, $part;
                }
        }

        if (defined $opts{fh})
        {
                return undef;
        }
        return join('', @{$r});
}

Testing Your Plugin

Restart your webserver and test the plugin as in the previous tutorial.

Sample Output

Explist.png