Using the new API

2011-07-20T12:29:58Z

DaveTarrant:

[[Category:EPrints Bazaar]]
The new EPrints API is exposes the basic functionality of a repository in clean way. The aim of the API is to be simple to use but powerful. Some of the more complex things EPrints can do are deliberately not exposed. Our aim is that the EPrints API will remain consistent between versions of the software so your plugins wont break when you upgrade eprints.

This exercise assumes that you have completed the [[My_First_Bazaar_Package]] exercise and will be expanding on the screen plug-in detailed in this exercise.

In this exercise we are going to expand our screen to take a parameter and process it. We shall use the API to retrieve information from within EPrints an display it on screen.

=Retrieving an object by ID=

==Reading EPrint ID from Address Bar Parameter==

In order to do this we are going to create some special action methods, these can perform operations when requested.

Taking the screen plug-in developed in the [[My_First_Bazaar_Package]] exercise, firstly add a global screen variable which we can store an eprint object inside.

our $eprint = undef;

This will be used later.

Next we want to define a couple of new methods, the first of which reads a parameter "input_field":

my $eprint_id = $repository->param( "input_field" );

and then retrieves the eprint corresponding to the value set by the parameter:

$eprint = $repository->eprint( $eprint_id );

In order to call these methods at the appropriate time lets add a whole method to our screen plug-in. Add the following near the top of the file:

sub action_process_input {

my ( $self ) = @_;

my $repository = $self->{repository};

my $eprint_id = $repository->param( "input_field" );

## DO SOME VALIDATION HERE MAYBE???

$eprint = $repository->eprint( $eprint_id );

if (!defined $eprint)
{
$self->{processor}->add_message(
"error",
$self->{repository}->make_text("No EPrint found with ID: $eprint_id")
);
}

}

At this point we can call this method from our existing render method to get a handle on the eprint object.

To do this add the following to the bottom of the existing render method:

$self->action_process_input();

You could make the action_process_input method return the eprint rather than set it as a global, however the reason to not do this will become apparent later.

Lastly, lets get the title of the EPrint an print it out.

Again add the following to the bottom of our render method:

if (defined $eprint) {
my $title = $eprint->get_value("title");

my $h1 = $repository->make_element("h1");
$h1->appendChild($repository->make_text($title));

$frag->appendChild($h1);
}

At this point you should be able to save and package your bazaar package (or just test it in line).

To test it point your web browser at the screen plug-in (by clicking it in the interface) and add a &input_field=X parameter to the end of the URL in the address bar. CHANGE X to a number which might be the id number of an EPrint.

==Reading EPrintID from input field==

This is an extension of the previous exercise, it does not work without it.

To do this we need to add an input form to our render method, this is a standard HTML input form. This needs to be added ABOVE the call to action_process_input!

Firstly lets make a form and append it to the output ($frag):

my $form = $repository->render_form("POST");
....
$frag->appendChild( $form );

Next lets add an input field to hold the value the user types in and append this to the form (between the lines above):

my $input_field = $repository->make_element(
"input",
name=> "input_field",
type=> "text"
);
$form->appendChild($input_field);

Then append a button which the user can press, note that a button is tied to an action on a screen, thus you can redirect people around eprints in this way to perform quiet complex actions.

my $submit_button = $screen->render_action_button(
{
action => "process_input",
screen => $screen,
screen_id => $screen_id,
} );
$form->appendChild($submit_button);

NOTE: This button requires the $screen and $screen_id parameters to be set. So somewhere earlier in the render method you need to add the following two lines:

my $screen_id = "Screen::".$self->{processor}->{screenid};
my $screen = $repository->plugin( $screen_id, processor => $self->{processor} );

Lastly in the render method we need to CHANGE the processing code added previously to handle both ways of handing the screen an eprint_id.

To do this, find the previously added $self->action_process_input() line and change this to the following:

my $input_value = $repository->param( "input_field" );

if ((!defined $eprint) and (defined $input_value)) {
$self->action_process_input();
}

Doing this will cause the input_field box which is POSTED from our form to be the primary source of eprint_id. However if there is no POST value, the render method will attempt to get the value passed in the URL.

Lastly we need to enable the action that the button is calling but registering it as an action on the screen. To do this add the following line to the Plug-ins new method:

$self->{actions} = [qw/ process_input /];

Actions also hold permissions that define which types of user can perform this action, in this case we are going to let everyone perform the action within this screen. The following method (which needs to be added below the can_be_viewed method) handles this. It is required!

sub allow_process_input
{
my ( $self ) = @_;

return 1;
}

=Rendering a citation and Making a new Citation=

==Rendering a Citation==

This is very simple, try changing the part in the render method where we fetch the title and append it to the following line only:

$frag->appendChild($eprint->render_citation("default"));

This will append the default citation for this EPrint to the screen.

==Making a New Citation (Optional)==

EPrint citations are defined as XML and stored in the cfg/citations/eprint/ directory (from the archive_name directory).

You can simple copy one of the provided ones and change it to include different fields or be in a different order, more on this soon.

=Doing a search and mapping a list (Harder)=

Taking our existing plug-in we now want to make our input box a search term "Observations" and print out a list of EPrints.

To do this we need to modify our action_process_input method and the render method from before.

==Searching==

First things first we need a place to store a list of eprints rather than just one. Let's declare (or change the existing) global variable eprints:

our $eprints = undef;

Next lets change the action_process_input method to perform a search, to do this find the line which reads the "input_field" parameter and change this:

my $input_value = $repository->param( "input_field" );

As this no longer represents an EPrint ID we'll rename the parameter.

You can delete all the lines after this in the action_process_input method as we are going to replace them all.

Next lets get the eprint dataset so we can search it:

my $eprint_dataset = $repository->dataset( "eprint" );

Now we are going to search on TITLE so lets define the filter for the search. Here we are doing a fuzzy search (the match => EX parameter is not used).

my @filters = (
{ meta_fields => [qw( title )], value => $input_value },
);

Now lets do the search and assign the output to our list of eprints:

$eprints = $eprint_dataset->search(
filters => \@filters,
custom_order=>"-datestamp",
limit => 10,
);

Notice that we are setting an order (based upon age) for the eprints to be listed in. Also we are limiting the number returned to 10.

Finally lets do some error handling if the list is empty and nothing was found. This is just a little more detailed than before.

if (!defined $eprints or $eprints->count < 1)
{
$self->{processor}->add_message(
"error",
$self->{repository}->make_text("No EPrints found to match search: $input_value")
);
}

==Rendering the output==

Lastly to display all the items in our list we need to change the render method.

To do this find the place where did the rendering before (it was inside an "if" statement).

To perform a bit more error checking lets firstly change the "if" statement slightly:

if (defined $eprints and $eprints->count > 0)

This will check there is actually something in the list as well as it being defined.

Next we need to iterate of the items in the list and print their citations.

This can be done using the following map function:

$eprints->map( sub {
my( undef, undef, $eprint ) = @_;

$frag->appendChild($eprint->render_citation("default"));
$frag->appendChild($repository->make_element("br"));
});

Here we can see that each item in the list is an eprint and we can simply render a citation for each followed by a newline.

==Extension exercise==

* Add a new parameter to allow the user to set a custom limit to the number of results which come back as a result of a search.
* Tidy up your style
* Define all the missing phrases

My First Bazaar Package

2011-07-20T12:23:29Z

DaveTarrant: Added back in the phrases section as an extension

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

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

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

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 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'' → ''System Tools'' → ''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

<?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($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.

[[Category:EPrints_Bazaar]]

My First Bazaar Package

2011-07-20T12:21:38Z

DaveTarrant:

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

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

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

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 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'' → ''System Tools'' → ''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

<?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($self->html_phrase("text"));

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

[[Category:EPrints_Bazaar]]

2011-03-29T15:13:48Z

DaveTarrant: /* Making a citation (optional) */

Using the new API

2011-03-29T15:05:35Z

DaveTarrant: /* Reading EPrintID from input field */

Using the new API

2011-03-29T15:05:08Z

DaveTarrant:

2010-12-14T16:45:50Z

DaveTarrant: Created page with 'EPM package guidelines state that you should use semantic version numbers for you package versions. This also makes upgrades easier. This page discusses why and gives an example.…'

EPM package guidelines state that you should use semantic version numbers for you package versions. This also makes upgrades easier. This page discusses why and gives an example.

=Semantic Versioning=

Semantic version numbers take the form X.X.X where all X's are numbers and can each be as large as you like. Another way of writing this version number is Major.Minor.Bugfix and is how we shall refer to them from now on.

==Bugfix Releases==

Bugfix releases of Bazaar packages should introduce '''NO''' extra functionality, they should also be able to be installed with '''NO''' user interaction. This way they can auto-update on the server if the user has specified this is OK.

==Minor Releases==

Minor releases can add functionality but as a guide should not change the features of that release or the underlying data model (if there is one). Minor release can require interaction from the user to install.

==Major Releases==

These are really up to the user to install and could completely change the functionality of a package (although not recommended). At this point you can do what you like :)

=Upgrade Methodology=

When an upgrade is done performed upon a package the '''postinst method is not called''' rather an '''upgrade''' method is called and passed the two version numbers. These version numbers correspond to the old version being upgraded and the new version being installed respectively.

==Files on Disk Upgrade==
This is the first stage of any upgrade.

* Any files belonging to the old version are removed or replaced by new versions.
* Any new files which were not there before are added.
* Any errors (e.g. files not under package management cos they have changed) results in an error and the old files are put back and the upgrade aborts.

==API Calls==
These would have been performed initially by the POSTINST method. However neither this nor the PRERM method are called during an upgrade. Any changes required between versions must be defined in the upgrade method.

==Data and Datasets==
Datasets are defined in config files, thus any dataset changes are applied.

No data is lost unless the field containing that data is no longer defined by any config file.

Interactive Install/Upgrade/Remove will allow the users to change this behaviour and keep the data even if it actually becomes inaccessible due to nothing in EPrints understanding it.

=Example=

The starting point for this is our Screen plug-in where the POSTINST and PRERM methods are defined (see [[XML manipulation of the EPrints Workflow using a Bazaar Package]]).

To enable upgrades we simply add an upgrade sub alongside these methods:

sub allow_action_upgrade
{
my ( $self ) = @_;

return 1;
}

# The upgrade method, this will call all upgrade subs individually between the old version number and the new version number.
sub action_upgrade
{
my ( $self, $old_version_number, $new_version_number ) = @_;

my @versions = qw(
0.0.1
0.0.2
);

for(my $i = 0; $i < $#versions; ++$i)
{
if( $old_version_number eq $versions[$i] )
{
no strict 'refs';
my $f = "upgrade_".$versions[$i]."_to_".$versions[$i+1];
$f =~ s/\./_/g;
&$f( $self );
$old_version_number = $versions[$i+1];
}
}
}

sub upgrade_0_0_1_to_0_0_2
{
my ( $self ) = @_;

print STDERR "IN THE UPGRADE ROUTINE FOR 0.0.1 to 0.0.2 \n\n";

# Add your API calls POSTINST like stuff here to upgrade versions.
}

So all you need to do is define potentially lots of upgrade_X_X_X_to_X_X_Z routines to handle all the upgrades.

If people are upgrading from 0.0.1 to 0.0.5 then potentially 4 of these upgrade methods will be called.

XML manipulation of the EPrints Workflow using a Bazaar Package

2010-12-13T13:37:59Z

DaveTarrant: /* Add a new depoist type */

Manipulation of built in EPrint files, such as the Workflows, is currently performed using the postinst method which is run after the rest of package is installed.

Likewise when the package is removed, the prerm method needs to call exactly the opposite set of operations to clean itself up before full removal.

As we go along we'll see that if you don't cleanup behind you, you won't even be able to re-install your same package again as the installer will detect conflicting data already in existence.

=Pre-Requisites=

To edit EPrints XML we need an epm package containing a spec file which points to a plug-in where we are going to put out postinst and prerm methods.

Below is a simple framework for your plug-in (it's a Screen plug-in so needs to go in the cfg/plugins/EPrints/Plugin/Screen/Admin directory). Remember to name it applicably and match this name with the one in the spec file.

package EPrints::Plugin::Screen::Admin::MYNAME;

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

use strict;

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

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

$self->{actions} = [qw/ postinst prerm /];

$self->{package_name} = "package_name";

return $self;
}

# Can this screen be viewed?
sub can_be_viewed
{
my( $self ) = @_;

return 0;
}

# Do we have a prerm method which needs executing?
sub allow_action_prerm
{
my ( $self ) = @_;

return 1;
}

# Do we have a postinst method which needs executing?
sub allow_action_postinst
{
my( $self ) = @_;

return 1;
}

# The postinst routine
sub action_postinst
{
my ( $self ) = @_;

my $repository = $self->{repository}->get_repository();

# Everthing went OK (why the hell did I code this the wrong way round?)
return (0,undef);
# Something went wrong
# return (1,"MUPPET!!!")
}

# The prerm routine
sub action_prerm
{
my ( $self ) = @_;

my $repository = $self->{repository}->get_repository();

return (0,undef);

}

# A render method for the screen, which we don't need unless we allow this screen to be viewed.
# If this screen is visible you return an html fragment, or redirect somewhere else, like a config file :)
sub render
{
my ( $self ) = @_;

return undef;
}

1;

=Remember how to force remove a broken package=

perl bin/epm archive_name remove package_name --force

=Exercise 1=

In this exercise we are going to do some simple workflow editing exercises. These follow the standard EPrints training materials which teach you how to manually edit the workflow. Here we are going to do all the same stuff with API calls.

=Adding a Divisions Stage to the Workflow=

Basically we are simply editing XML so all we need to do is tell the repository which file to manipulate and then give it the stuff add to this file.

So to the '''postinst''' routine we need to add the following lines. Note that you '''don't''' need to manually specify your package_name

my $filename = $repository->config( "config_path" )."/workflows/eprint/default.xml";

# Gap for the stuff to be defined we need to add

my $rc = EPrints::XML::add_to_xml( $filename, $xml, $self->{package_name} );

At the same time then it is worth adding the equivalent remove lines to the '''prerm''' method. Again you need to specify your package name.

my $filename = $repository->config( "config_path" )."/workflows/eprint/default.xml";

EPrints::XML::remove_package_from_xml( $filename, $self->{package_name} );

Note that the remove call does not return a state as it will be able to remove anything, but it won't error if there is nothing to remove. Thus all return states are OK (this may change if someone can think of an exception)

Lastly we need to actually tell the postinst method the block of XML to add.

my $string = '
<workflow xmlns="http://eprints.org/ep3/workflow" xmlns:epc="http://eprints.org/ep3/control">
<flow>
<stage ref="divisions"/>
</flow>
<stage name="divisions">
<component type="Field::Subject">
<field ref="divisions" required="yes" />
</component>
</stage>
</workflow>
';

my $xml = EPrints::XML::parse_string( undef, $string );
$xml = EPrints::XML::_remove_blank_nodes($xml);
my $node = $xml->getFirstChild();

Here you can see that we can simply specify the XML as a string. We can then either parse this string and send a dom object to the add method, or simply send the string and let the add_to_xml method do it for us.

If you want to parse it yourself you will need the following code block:

my $xml = EPrints::XML::parse_string( undef, $string );

The XML represents the exact same tree as in the workflow XML file we are attempting to edit. You can view this by clicking the "View Configuration" button on the "Config. Tools" tab of the admin screen. Once here you will need to scroll down to find the file you specified (in this case /workflows/eprint/default.xml). Since it represents the same tree, only nodes which don't exist are added and marked as belonging to your package. This marker is how they are removed.

Alternatively you can build an XML tree using the EPrints::XML methods like make_element("flow") etc. At this point (unless you added blank nodes) you won't need the remove line, but it doesn't hurt to leave it in there.

Finally make sure you have all your variables like $rc (return code) defined and then this screen should be ready.

==Divisions Phrases==

For the divisions screen to work fully you will need to define a number of phrases.

As usual you need a new file, basically take a copy of cfg/lang/en/phrases/zz_webcfg in cfg/lang/en/phrases/package_name.

The clear all the defined phrases from this file and add the follow 2:

<nowiki><epp:phrase id="metapage_title_divisions">Divisions</epp:phrase></nowiki>
<nowiki><epp:phrase id="Plugin/InputForm/Component/Field/Subject:divisions_search_bar"><div class="ep_subjectinput_searchbar">Search for division: <epc:pin name="input"/> <epc:pin name="search_button"/> <epc:pin name="clear_button"/></div></epp:phrase></nowiki>

=Package and Test=

Finally, package all these files up and test in from the Bazaar. Note that in the spec file you need to set your configuration file to Admin::PackageName or whatever your screen is called.

You can test this package by click the "manage deposits" link in the admin toolbar and adding a new item. You should see a divisions tab.

=Exercise 2=

Change this package to add a conditional element somewhere, for example:

<epc:if test="type = 'book'">
<field ref="pres_type"/>
</epc:if>

Experiment with this and use the "view configuration" to see what your changes do to the workflow file each time.

Clue: The correct place to put this code block is under the <component type="Field::Multi"> tag which is in the core stage <stage name="core">. You need to wrap the above code blog in both these tags.

If you are using the same package as before you will need to updated your cached version and then restart apache to make it work. This is a known bug and applies the the XML manipulation code only.

=Exercise 3=

Here we are going to define a whole new type "map" and a different set of stages for it.

This exercise is also one of manual customisation exercises we run.

==Add a new depoist type==

This stage involves the editing of the repository namedsets, specifically the eprints namedset.

Again this used to be an entirely manual process however it can now be done with an API call via the postinst/prerm methods:

In '''postinst''':

# Load your namedset, in this case the eprint namedset
my $namedset = EPrints::NamedSet->new( "eprint",repository => $repository );

# Add a new option (string type, package_name, offset from top)
# Setting the offset to 0 will add the item at the top of list of eprint types in this case.
$namedset->add_option( "map", $self->{package_name}, 0 );

In '''prerm''' we need the corresponding remove calls!

my $namedset = EPrints::NamedSet->new( "eprint",repository => $repository );

$namedset->remove_option( "map", $self->{package_name} );

Each namedset item also needs some phrase so in our phrase file we need to add phrases for "eprint_typename_map" and "eprint_optdetails_type_map". Lets set these to "Map" and "A map or chart." respectively.

==Adding a new stage and simple map workflow==

In this section we are going to define a whole new workflow for our "map" type, so if someone selects this as their EPrint type they won't see upload (files), subjects and divisions, just a new state we going to call "map_stage".

Of course in order to customise the workflow we need to handle if/else statements. Helpfully there is a clever API call that does it for you.

All we have to define in the types we want to match and the stages that these types have. Everything that doesn't match thus goes in the else condition.

So in our postinst lets now define some variables

#our matching types
my @types = ( "map" );

#the stages
my @stages = ( "map_stage" );

Then we add these to our workflow with a similar API call to before (note the inclusion of the package_name!)

$rc = EPrints::Workflow::add_workflow_flow( $repository, $filename, "package_name", \@types, \@stages );

We can then use the xml string which we defined before to add the new stage:

my $string = '
<workflow xmlns="http://eprints.org/ep3/workflow" xmlns:epc="http://eprints.org/ep3/control">
<stage name="map_stage">
<component type="Field::Multi">
<title>Publisher Details</title>
<field ref="place_of_pub" />
<field ref="publisher" required="yes" />
<field ref="date" />
<field ref="date_type" />
</component>
<component>
<field ref="id_number" />
</component>
<component>
<field ref="official_url"/>
</component>
</stage>
</workflow>
';

=Package and Test=

Finally, package all these files up and test in from the Bazaar.

You can test this package by click the "manage deposits" link in the admin toolbar and adding a new item. You should now have a new eprint type on the first screen called "map" and selecting this will give you a much shorter workflow containing only a few fields.

Are all your phrases defined?