Difference between revisions of "My First Bazaar Package"

From EPrints Documentation
Jump to: navigation, search
(Re-Ordered instructions)
(27 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
=Introduction=
 
=Introduction=
In this tutorial we look at how to create a simple Bazaar Package (epm) ready for distribution via the EPrints Bazaar Store.
 
  
We are going to create this example simple and create a simple screen plug-in which will simply say hello to the user.  
+
In this tutorial you will create a "Hello, World" Screen and package it as a Bazaar Package (.epm).
  
It will read from a config file a variable which it will repeat back to the user.
+
=Requirements=
  
=Remember the steps to create an epm=
+
You will need a working EPrints installation on which you have an administrator account. You will need to have access to the command line to create the files for the package.
  
* Make it work first locally
+
=Step 1 - Create a blank package=
* Package up a working version with a spec file and icon.
 
* Install from the "Local Packages" tab in the bazaar to test it.
 
  
=Exercise=
+
In ''Admin'' → ''System Tools'' → ''EPrints Bazaar'', select the ''Developer Tools'' tab.
  
By this point you should have an EPrints Bazaar capable version of EPrints installed and have a repository set up of which you are the admin user.  
+
At the bottom of this screen is a form to create a new EPM. Enter the name (without quotes) "hello_world" and click ''Create''.
  
You should also have a command line (or other method) for accessing and creating files within the repository directory.  
+
You can fill out the metadata if you wish but at this stage you are only required to have a ''version'', which defaults to "1.0.0".
  
In this demo we are assuming that your root directory is always the archive's home folder found at eprints/archives/archive_name (where archive_name is your archive ID)
+
Click ''Save and Return'' to return to the EPrints Bazaar screen.
  
==Step 1 - Decide a Package Name==
+
If you make a mistake you can click ''Edit'' on the ''Developer Tools'' tab to re-edit the package.
  
I'm going to call my package eprints_test_package which I shall use throughout this exercise, let's hope its unique!
+
=Step 2 - Add an Icon=
  
To check it is unique, create a eprints_test_package.spec file with the following content:
+
Create an Icon, using the icon builder at http://bazaar.eprints.org
  
  package: eprints_test_package
+
OR
  version: 0.1
 
  title: Davetaz's First Package
 
  description: I'll add one later
 
  creator: Dave Tarrant <davetaz@foo.bar.org>
 
  icon: icon.png
 
  
You will have to find a random small icon you can use as well, a package without one isn't accepted!
+
Download the hello_world icon from http://bazaar.eprints.org/images/hello_world.png
  
We then package up our spec file and icon only into the root level of a zip file in this case called eprints_test_package.epm
+
Once you have this icon, name it hello_world.png and move it into the lib/static/images/epm/ directory.
  
Finally using the "Local Packages" tab in the Bazaar screen, upload your package. If you get a green tick back you have a unique name.
 
  
NOTE: This process does not secure you the package name! You can't camp on a name! You secure the name by uploading a working version of your package.
+
=Step 3 - Develop your package contents=
  
==Step 2 - Develop your package==
+
You will need to be in the root directory of your EPrints installation (typically /opt/eprints3).
  
In this example we shall make 3 files, a screen, a config file and a phrase file at the following locations:
+
''gedit'' is the Gnome Text editor but you can use any editor that is capable of creating text files.
  
* cfg/plugins/EPrints/Plugin/Screen/Admin/EPrintsTestScreen.pm
+
==Hello.pm==
* cfg/cfg.d/eprints_test_package.pl
 
* cfg/lang/en/phrases/eprints_test_package.xml
 
  
In each of these files copy and paste the following:
+
Create the directory to contain the ''Screen'' plugin you're going to package:
  
===EPrintsTestScreen.pm===
+
$ mkdir -p lib/plugins/EPrints/Plugin/Screen/
  
  package EPrints::Plugin::Screen::Admin::EPrintsTestScreen;
+
Create the screen plugin using your preferred text editor and add the sample content below:
 
+
 
  @ISA = ( 'EPrints::Plugin::Screen' );
+
$ gedit lib/plugins/EPrints/Plugin/Screen/Hello.pm
 
+
 
  use strict;
+
<source lang="perl">
  # Make the plug-in
+
package EPrints::Plugin::Screen::Hello;
  sub new
+
  {
+
@ISA = ( 'EPrints::Plugin::Screen' );
        my( $class, %params ) = @_;
+
 
+
use strict;
        my $self = $class->SUPER::new(%params);
+
# Make the plug-in
 
+
sub new
        # Where the button to access the screen appears if anywhere, and what priority
+
{
        $self->{appears} = [
+
    my( $class, %params ) = @_;
                {
+
                        place => "admin_actions",
+
    my $self = $class->SUPER::new(%params);
                        position => 1247,
+
                },
+
    # Where the button to access the screen appears if anywhere, and what priority
        ];
+
    $self->{appears} = [
 
+
      {
        return $self;
+
          place => "admin_actions",
  }
+
          position => 1247,
 
+
      },
  # Can anyone see this screen.
+
    ];
  sub can_be_viewed
+
  {
+
    return $self;
        my( $plugin ) = @_;
+
}
 
+
        return 1;
+
# Anyone can see this screen
  }
+
sub can_be_viewed { 1 }
 
+
  # What to display
+
# What to display
  sub render
+
sub render
  {
+
{
        my( $self ) = @_;
+
    my( $self ) = @_;
 
    
 
    
        my $repository = $self->{repository};
+
    # Get the current repository object (so we can access the users, eprints information about things in this repository)
 
    
 
    
        my $ret = $repository->make_doc_fragment();
+
    my $repository = $self->{repository};
        my $br = $repository->make_element("br");
 
 
    
 
    
        my $lang_phrase = $self->html_phrase("eprints_test_phrase");
+
    # Create an XML element to return to our screen
 
    
 
    
        my $text_from_config = $repository->make_text($repository->{config}->{eprints_test_package}->{phrase});
+
    my $frag = $repository->xml->create_document_fragment();
 +
 +
    # Fill the fragment with stuff
 
    
 
    
        $ret->appendChild($lang_phrase);
+
    $frag->appendChild($repository->xml->create_text_node( "Hello, World!" ));
        $ret->appendChild($br);
 
        $ret->appendChild($text_from_config);
 
 
    
 
    
        return $ret;
+
    return $frag;
 
+
}
  }
+
 
+
1;
  1;
+
</source>
 
 
===cfg/cfg.d/eprints_test_package.pl===
 
 
 
  $c->{eprints_test_package}->{phrase} = "This is a phrase, but it shouldn't be we are just testing. It could be a version number or some other variable.";
 
  
===cfg/lang/en/phrases/eprints_test_package.xml===
+
==hello_world.pl==
  
Finally we need some phrases. The title and description phrases are required if you are going to allow access to the screen from one of the admin menus.
+
Create the package directory that will contain the package's configuration file:
  
  <?xml version="1.0" encoding="utf-8" standalone="no"?>
+
$ mkdir -p lib/epm/hello_world/cfg/cfg.d
  <!DOCTYPE phrases SYSTEM "entities.dtd">
 
  <epp:phrases xmlns="http://www.w3.org/1999/xhtml" xmlns:epp="http://eprints.org/ep3/phrase" xmlns:epc="http://eprints.org/ep3/control">
 
 
 
    <epp:phrase id="Plugin/Screen/Admin/EPrintsTestScreen:title">Davetaz's Test Screen</epp:phrase>
 
    <epp:phrase id="Plugin/Screen/Admin/EPrintsTestScreen:description">I really need a description</epp:phrase>
 
 
 
    <epp:phrase id="Plugin/Screen/Admin/EPrintsTestScreen:eprints_test_phrase">This is our test phrase.</epp:phrase>
 
 
 
  </epp:phrases>
 
  
 +
Create a configuration file that enables the plugin - this file is copied into the repository when the package is enabled:
  
==Step 3 - Does it work locally==
+
$ gedit lib/epm/hello_world/cfg/cfg.d/hello_world.pl
  
You should now have the 3 files in place and if you reload your config (via the "Reload Configuration" button on the "Config. Tools" tab of the admin interface) you should then be able to go to the "Misc. Tools" tab and find your screen. Clicking on it should show our two phrases, one from the phrase file and one from the config listed on 2 different lines.
+
$c->{plugins}{"Screen::Hello"}{params}{disable} = 0;
  
==Step 3b - HELP - It didn't work==
+
'''NOTE All plugins in lib/plugins are disabled by default (see EPrints::PluginFactory::new) UNLESS you explicitly set the disable property in the plugin (and it doesn't make sense to set disable = 0 in the plugin because that would make it visible to all of your repositories even if they hadn't explicitly enabled your bazaar package).
  
If you made an error then the error message will likely be in the web servers error log.
+
=Step 4 - Build the Package=
  
Here is a very useful command for full debugging of EPrints and restarting the web server at the same time.
+
Re-Edit your EPM in the "Developer Tools" section of the Bazaar Store.  
  
In a new terminal as root, type and execute the following (on debian based systems):
+
At the bottom of the screen (the ''Files'' selector) you need to add the two files you created above:
  
  apache2ctl restart && tail -f /var/apache2/logs/error_log
+
* epm/hello_world/cfg/cfg.d/hello_world.pl
 +
* plugins/EPrints/Plugin/Screen/Hello.pm
 +
* static/images/epm/hello_world.png
  
This will restart the web server and then give you a live view on the error log.
+
=Step 5 - Enable and test the package=
  
Attempting to reload your screen again (hit F5) will the cause the error to be displayed instantly in this terminal. It is recommended to leave this terminal open for debugging at all times.
+
On the EPrints Bazaar ''Installed'' tab click ''Enable'' for the '''hello_world''' package. After a short time you should see a repository configuration reloaded message.
  
==Step 4 - Package it up and test it==
+
In ''Admin'' &rarr; ''System Tools'' &rarr; ''Misc. Tools'' you should now a button-link to your plugin (although with a missing phrase).
  
Now what we want to do is create a directory for our package (even better an svn or other change management system!) and move the files we just created out of the repository and into a directory which we can build out package from.  
+
You can now use ''Uninstall'' to completely remove the package and the source files created. A copy of the package will be saved in '''var/cache/epm/hello_world-1.0.0.epm'''.
  
So in your home directory (not the eprints one) make a folder for your package and move the files into it including the spec file and icon.
+
=Step 6 - Adding the missing phrases=
  
IMPORTANT: The directory structure needs to be preserved thus your directory listing should look as follows:
+
As EPrints is designed to be multi-language, phrases should be used instead of embedded text.
  
* icon.png
+
In this section we add the phrase file to define a name a description for our screen.
* eprints_test_package.spec
 
* cfg/plugins/EPrints/Plugin/Screen/Admin/EPrintsTestScreen.pm
 
* cfg/cfg.d/eprints_test_package.pl
 
* cfg/lang/en/phrases/eprints_test_package.xml
 
  
With this done, reload the config on your repository to make sure the screen has gone! You can even use view config to make sure all the related files have gone.
+
Create the English language directory that will contain the package's English language phrase file:
  
Finally package up your directory using zip to make an epm called eprints_test_package.epm as before and upload this via the "Local Packages" tab, you may need to remove the old one first! Also did you version your package from the initial 0.1 marker in the spec file. (Get a script to grab the SVN version to go here when you build a propper package)
+
$ mkdir -p lib/lang/en/phrases/
  
With all this done, if you have a green box, click the install button and see if it worked!
+
Create a phrase file:
  
If it didn't you will need to remove it (if it installed) and use the steps outlined in 3b to debug why.  
+
$ gedit lib/lang/en/phrases/hello_world.xml
  
==Step 4b - I'm stuck in limbo, package won't remove (a.k.a. using epm via the command line)==
+
<source lang="xml">
 +
  <?xml version="1.0" encoding="iso-8859-1" standalone="no" ?>
 +
  <!DOCTYPE phrases SYSTEM "entities.dtd">
 +
 
 +
  <epp:phrases xmlns="http://www.w3.org/1999/xhtml" xmlns:epp="http://eprints.org/ep3/phrase" xmlns:epc="http://eprints.org/ep3/control">
 +
 +
        <epp:phrase id="Plugin/Screen/Hello:title">Hello</epp:phrase>
 +
        <epp:phrase id="Plugin/Screen/Hello:description">My First Bazaar Package</epp:phrase>
 +
       
 +
        <epp:phrase id="Plugin/Screen/Hello:text">Hello World - This is the my first bazaar package calling.</epp:phrase>
 +
 +
  </epp:phrases>
 +
</source>
 +
 +
Don't worry too much about the wrapping here, the important thing are the phrases of which we have created 3.
  
If you get stuck you can use the command line scripts which allow you to force changes.  
+
Note that 2 of these (the top 2) will get used instantly by our package however the 3rd needs to be added to the render method of our screen.  
  
You have to be aware that forcing changes means that any errors (prerm and dataset removals etc) will be ignored!
+
In order to do this edit the Hello.pm screen created in Step 1 and add the following in the appropriate place in the render method.
  
The syntax is as follows (and needs to be executed as the eprints user at the root level of the eprints home directory)
+
  $frag->appendChild($repository->xml->create_element("br"));
 +
  $frag->appendChild($self->html_phrase("text"));
  
  perl bin/epm archive_name [install|remove] package_name [--force]
+
For some hints on loading and manipulating EPrints see [[Manipulating eprints in 3.2]].
  
This basically replicates the graphically functionality except the addition of the --force flag. Search functionality is still to be added... maybe.
+
'''Don't Forget''' to add the phrase file to your bazaar package using the developer tools tab.
  
=Exercise 2=
+
'''WARNING: if your package overrides any existing EPrints phrases then your overrides will be applied to ALL repositories even if they have not enabled your package. In this case you would add your override phrases to a separate file - eg. lib/epm/hello_world/cfg/lang/en/phrases/hello_world_overrides.xml - this file will then only be considered when a repository enables your package.
  
That the easy exercise done, so how about doing something a little more challenging.
+
[[Category:EPrints_Bazaar]]
 
 
How about using our config file to specify an eprint_id or search expression and then using your screen to display something about this item/list.
 
 
 
For some hints on loading and manipulating EPrints see [[Manipulating eprints in 3.2]].
 

Revision as of 09:15, 3 August 2012

Introduction

In this tutorial you will create a "Hello, World" Screen and package it as a Bazaar Package (.epm).

Requirements

You will need a working EPrints installation on which you have an administrator account. You will need to have access to the command line to create the files for the package.

Step 1 - Create a blank package

In AdminSystem ToolsEPrints Bazaar, select the Developer Tools tab.

At the bottom of this screen is a form to create a new EPM. Enter the name (without quotes) "hello_world" and click Create.

You can fill out the metadata if you wish but at this stage you are only required to have a version, which defaults to "1.0.0".

Click Save and Return to return to the EPrints Bazaar screen.

If you make a mistake you can click Edit on the Developer Tools tab to re-edit the package.

Step 2 - Add an Icon

Create an Icon, using the icon builder at http://bazaar.eprints.org

OR

Download the hello_world icon from http://bazaar.eprints.org/images/hello_world.png

Once you have this icon, name it hello_world.png and move it into the lib/static/images/epm/ directory.


Step 3 - Develop your package contents

You will need to be in the root directory of your EPrints installation (typically /opt/eprints3).

gedit is the Gnome Text editor but you can use any editor that is capable of creating text files.

Hello.pm

Create the directory to contain the Screen plugin you're going to package:

$ mkdir -p lib/plugins/EPrints/Plugin/Screen/

Create the screen plugin using your preferred text editor and add the sample content below:

$ gedit lib/plugins/EPrints/Plugin/Screen/Hello.pm
 package EPrints::Plugin::Screen::Hello;
 
 @ISA = ( 'EPrints::Plugin::Screen' );
 
 use strict;
 # Make the plug-in
 sub new
 {
    my( $class, %params ) = @_;
 
    my $self = $class->SUPER::new(%params);
 
    # Where the button to access the screen appears if anywhere, and what priority
    $self->{appears} = [
       {
           place => "admin_actions",
           position => 1247,
       },
    ];
 
    return $self;
 }
 
 # Anyone can see this screen
 sub can_be_viewed { 1 }
 
 # What to display
 sub render
 {
    my( $self ) = @_;
  
    # Get the current repository object (so we can access the users, eprints information about things in this repository)
  
    my $repository = $self->{repository};
  
    # Create an XML element to return to our screen
  
    my $frag = $repository->xml->create_document_fragment();
 
    # Fill the fragment with stuff
  
    $frag->appendChild($repository->xml->create_text_node( "Hello, World!" ));
  
    return $frag;
 }
 
 1;

hello_world.pl

Create the package directory that will contain the package's configuration file:

$ mkdir -p lib/epm/hello_world/cfg/cfg.d

Create a configuration file that enables the plugin - this file is copied into the repository when the package is enabled:

$ gedit lib/epm/hello_world/cfg/cfg.d/hello_world.pl
$c->{plugins}{"Screen::Hello"}{params}{disable} = 0;

NOTE All plugins in lib/plugins are disabled by default (see EPrints::PluginFactory::new) UNLESS you explicitly set the disable property in the plugin (and it doesn't make sense to set disable = 0 in the plugin because that would make it visible to all of your repositories even if they hadn't explicitly enabled your bazaar package).

Step 4 - Build the Package

Re-Edit your EPM in the "Developer Tools" section of the Bazaar Store.

At the bottom of the screen (the Files selector) you need to add the two files you created above:

  • epm/hello_world/cfg/cfg.d/hello_world.pl
  • plugins/EPrints/Plugin/Screen/Hello.pm
  • static/images/epm/hello_world.png

Step 5 - Enable and test the package

On the EPrints Bazaar Installed tab click Enable for the hello_world package. After a short time you should see a repository configuration reloaded message.

In AdminSystem ToolsMisc. Tools you should now a button-link to your plugin (although with a missing phrase).

You can now use Uninstall to completely remove the package and the source files created. A copy of the package will be saved in var/cache/epm/hello_world-1.0.0.epm.

Step 6 - Adding the missing phrases

As EPrints is designed to be multi-language, phrases should be used instead of embedded text.

In this section we add the phrase file to define a name a description for our screen.

Create the English language directory that will contain the package's English language phrase file:

$ mkdir -p lib/lang/en/phrases/

Create a phrase file:

$ gedit lib/lang/en/phrases/hello_world.xml
  <?xml version="1.0" encoding="iso-8859-1" standalone="no" ?>
  <!DOCTYPE phrases SYSTEM "entities.dtd">
  
  <epp:phrases xmlns="http://www.w3.org/1999/xhtml" xmlns:epp="http://eprints.org/ep3/phrase" xmlns:epc="http://eprints.org/ep3/control">
 
        <epp:phrase id="Plugin/Screen/Hello:title">Hello</epp:phrase>
        <epp:phrase id="Plugin/Screen/Hello:description">My First Bazaar Package</epp:phrase>
        
        <epp:phrase id="Plugin/Screen/Hello:text">Hello World - This is the my first bazaar package calling.</epp:phrase>
 
  </epp:phrases>

Don't worry too much about the wrapping here, the important thing are the phrases of which we have created 3.

Note that 2 of these (the top 2) will get used instantly by our package however the 3rd needs to be added to the render method of our screen.

In order to do this edit the Hello.pm screen created in Step 1 and add the following in the appropriate place in the render method.

 $frag->appendChild($repository->xml->create_element("br"));
 $frag->appendChild($self->html_phrase("text"));

For some hints on loading and manipulating EPrints see Manipulating eprints in 3.2.

Don't Forget to add the phrase file to your bazaar package using the developer tools tab.

WARNING: if your package overrides any existing EPrints phrases then your overrides will be applied to ALL repositories even if they have not enabled your package. In this case you would add your override phrases to a separate file - eg. lib/epm/hello_world/cfg/lang/en/phrases/hello_world_overrides.xml - this file will then only be considered when a repository enables your package.