Difference between revisions of "My First Bazaar Package"

From EPrints Documentation
Jump to: navigation, search
m
m (links updated)
 
(14 intermediate revisions by 6 users not shown)
Line 2: Line 2:
  
 
In this tutorial you will create a "Hello, World" Screen and package it as a Bazaar Package (.epm).
 
In this tutorial you will create a "Hello, World" Screen and package it as a Bazaar Package (.epm).
 +
 +
The page also references using a code versioning tool; [https://git-scm.com Git]. The goal is to have your EPM source files managed through Git and be able to edit them in a live repository.
 +
 +
Tracking files in Git is more complex but allows easier development. All of your package's files are placed under a directory tree then Sym-linked into the correct locations in EPrints. The [[API:tools/epm]] tool provides a ''link_lib'' option that makes this easier to achieve, as long as you follow the directory layout described below.
 +
As an alternative to using the web for building/customising your package you can try [https://github.com/eprintsug/gitaar Gitaar], a tool for building the epmi metadata file and EPM suitable for sharing.
 +
 +
'''Warning!''' do not edit files and then enable/disable or install/uninstall an EPM. The EPM will detect the changed files and either create backups or refuse to work. You must edit the EPM and do ''Save and Return'' to re-scan the EPM's files (in Admin → EPrints Bazaar, Developer Tools).
  
 
=Requirements=
 
=Requirements=
Line 7: Line 14:
 
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.
 
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 - Develop your package contents=
+
If using Git, you need to have it installed on your server.
 +
 
 +
 
 +
= Create a blank package=
 +
 
 +
In ''Admin'' → ''System Tools'' → ''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.
 +
 
 +
The GUI will create the lib/epm/hello_world directory tree for you.
 +
 
 +
 
 +
= Add blank EPM to Git =
 +
 
 +
This step is performed on your Eprints server.
 +
 
 +
Initialise and configure your git repository
 +
cd lib/epm/hello_world
 +
git init
 +
git add .
 +
git commit -a -m 'Blank EPM started via web'
 +
 
 +
 
 +
= Develop your package contents=
  
 
You will need to be in the root directory of your EPrints installation (typically /opt/eprints3).
 
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.
 
''gedit'' is the Gnome Text editor but you can use any editor that is capable of creating text files.
 +
 +
 +
== Add an Icon ==
 +
 +
Create an icon, e.g. using [http://bazaar.eprints.org/223/ Bazaar's icon builder].
 +
 +
OR
 +
 +
Download the hello_world icon from [https://bazaar.eprints.org/393/1/static/images/epm/Hello.png Bazaar].
 +
 +
Once you have this icon, name it hello_world.png and move it into lib/epm/hello_world/lib/static/images/epm/ directory.
  
 
==Hello.pm==
 
==Hello.pm==
Line 23: Line 70:
 
  $ gedit lib/plugins/EPrints/Plugin/Screen/Hello.pm
 
  $ gedit lib/plugins/EPrints/Plugin/Screen/Hello.pm
  
 +
<source lang="perl">
 
  package EPrints::Plugin::Screen::Hello;
 
  package EPrints::Plugin::Screen::Hello;
 
   
 
   
Line 65: Line 113:
 
    
 
    
 
     $frag->appendChild($repository->xml->create_text_node( "Hello, World!" ));
 
     $frag->appendChild($repository->xml->create_text_node( "Hello, World!" ));
 
+
 
 
     return $frag;
 
     return $frag;
 
  }
 
  }
 
   
 
   
 
  1;
 
  1;
 +
</source>
  
 
==hello_world.pl==
 
==hello_world.pl==
Line 83: Line 132:
 
  $c->{plugins}{"Screen::Hello"}{params}{disable} = 0;
 
  $c->{plugins}{"Screen::Hello"}{params}{disable} = 0;
  
=Step 2 - Add an Icon=
+
'''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).
 +
 
 +
Tip: Any files you add below '''cfg/''' and are tracked by the EPM will be added to the repository when the EPM is enabled.
 +
 
  
Create an Icon, using the icon builder at http://bazaar.eprints.org
+
== Commit changes ==
  
OR
+
After adding new files its important to record the changes
  
Download the hello_world icon from http://bazaar.eprints.org/images/hello_world.png
+
Add all new files
 +
git add .  
  
Once you have this icon, name it hello_world.png and move it into the lib/static/images/epms/ directory.
+
Commit them with a message
  
=Step 3 - Create a blank package=
+
git commit -a -m "Added new Screen and its configuration. Also included new image"
  
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''.
+
= Build the Package=
  
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".
+
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:
+
At the bottom of the screen (the ''Files'' selector) you need to add the files you created above:
  
 
* epm/hello_world/cfg/cfg.d/hello_world.pl
 
* epm/hello_world/cfg/cfg.d/hello_world.pl
Line 107: Line 159:
 
* static/images/epm/hello_world.png
 
* static/images/epm/hello_world.png
  
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.
+
= Testing in place =
 +
 
 +
Use the ''link_lib'' argument in [[API:tools/epm]] to sym-link the plugin into your live repository:
 +
 
 +
./tools/epm link_lib hello_world
 +
 
 +
If needed, also include configuration
 +
./tools/epm link_cfg REPOID hello_world
 +
 
 +
Followed by
 +
tools/epm enable REPOID hello_world
  
=Step 4 - Enable and test the package=
+
= 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.
 
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.
Line 119: Line 180:
 
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'''.
 
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=
+
 
 +
= Adding the missing phrases=
  
 
As EPrints is designed to be multi-language, phrases should be used instead of embedded text.
 
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.
+
In this section we add the phrase file to define a title and a description for our screen.
  
 
Create the English language directory that will contain the package's English language phrase file:
 
Create the English language directory that will contain the package's English language phrase file:
Line 133: Line 195:
 
  $ gedit lib/lang/en/phrases/hello_world.xml
 
  $ gedit lib/lang/en/phrases/hello_world.xml
  
 +
<source lang="xml">
 
   <?xml version="1.0" encoding="iso-8859-1" standalone="no" ?>
 
   <?xml version="1.0" encoding="iso-8859-1" standalone="no" ?>
 
   <!DOCTYPE phrases SYSTEM "entities.dtd">
 
   <!DOCTYPE phrases SYSTEM "entities.dtd">
Line 144: Line 207:
 
   
 
   
 
   </epp:phrases>
 
   </epp:phrases>
 +
</source>
 
   
 
   
Don't worry too much about the wrapping here, the important thing are the phrases of which we have created 3.  
+
Don't worry too much about the wrapping here, the important thing is 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.  
 
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.  
Line 156: Line 220:
 
For some hints on loading and manipulating EPrints see [[Manipulating eprints in 3.2]].
 
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.
+
'''Don't Forget''' to add the phrase file to your bazaar package using the developer tools tab and commit them to git!
 +
 
 +
'''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]]
 
[[Category:EPrints_Bazaar]]

Latest revision as of 09:53, 6 August 2019

Introduction

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

The page also references using a code versioning tool; Git. The goal is to have your EPM source files managed through Git and be able to edit them in a live repository.

Tracking files in Git is more complex but allows easier development. All of your package's files are placed under a directory tree then Sym-linked into the correct locations in EPrints. The API:tools/epm tool provides a link_lib option that makes this easier to achieve, as long as you follow the directory layout described below. As an alternative to using the web for building/customising your package you can try Gitaar, a tool for building the epmi metadata file and EPM suitable for sharing.

Warning! do not edit files and then enable/disable or install/uninstall an EPM. The EPM will detect the changed files and either create backups or refuse to work. You must edit the EPM and do Save and Return to re-scan the EPM's files (in Admin → EPrints Bazaar, Developer Tools).

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.

If using Git, you need to have it installed on your server.


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.

The GUI will create the lib/epm/hello_world directory tree for you.


Add blank EPM to Git

This step is performed on your Eprints server.

Initialise and configure your git repository

cd lib/epm/hello_world
git init
git add .
git commit -a -m 'Blank EPM started via web'


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.


Add an Icon

Create an icon, e.g. using Bazaar's icon builder.

OR

Download the hello_world icon from Bazaar.

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

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

Tip: Any files you add below cfg/ and are tracked by the EPM will be added to the repository when the EPM is enabled.


Commit changes

After adding new files its important to record the changes

Add all new files

git add . 

Commit them with a message

git commit -a -m "Added new Screen and its configuration. Also included new image"


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


Testing in place

Use the link_lib argument in API:tools/epm to sym-link the plugin into your live repository:

./tools/epm link_lib hello_world

If needed, also include configuration

./tools/epm link_cfg REPOID hello_world

Followed by

tools/epm enable REPOID hello_world

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.


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 title and 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 is 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 and commit them to git!

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.