View source for My First Bazaar Package

=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 ''Admin'' &rarr; ''System Tools'' &rarr; ''EPrints 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/epms/ 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

<source lang="perl">
 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;
</source>

==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 - 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 ''Admin'' &rarr; ''System Tools'' &rarr; ''Misc. 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 5 - 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

<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. 

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.

[[Category:EPrints_Bazaar]]