EPrints Documentation - User contributions [en-gb]

How to write plugins

2015-11-02T16:12:37Z

Dkane: /* You will need */

[[Category:Plugins]]
[[Category:Contribute]]

== What is a Plugin? ==

The plugin system for EPrints 3 has been developed to make it easy and share the most common extensions to the code without having to hack the core system (and causing yourself problems with upgrades etc.)

Plugins are a way to make functionality easy to maintain and transfer. If you make any customizations to your repository other than metadata and appearence changes then you will probably want to write a plugin.

== You will need ==
* A basic understanding of perl (don't be scared - its not hard and there are plenty of tutorials on the web)

* An EPrints installation to play about on. A Virtual box with [[:Category:Installation|EPrints installed]] is ideal.

* Information from the [[:Category:API|EPrints API]]

* For some types of plugin you might also find some Javascript and CSS knowledge helpful.

== Write a Plugin! ==

When the system loads, it automatically loads all modules in the archives/ARCHIVE_ID/cfg/plugins/EPrints/Plugin/ directory, so for simple plugins you just drop them in that directory and you're done!

When a plugin is loaded it has a registration method which is called which tells the core EPrints system what this plugin does. EPrints then makes it available as appropriate.

Clever plugins can detect features they need and adapt to use the tools available, or disable themselves if they are missing required tools (rather than crash the system). Some specialised plugins are disabled in their default state and must be enabled in the repository configuration.

Another cool thing is that plugins are Perl Objects, which means you can subclass them. Here's an real-world example: We have a research group which uses BibTeX but over the years standardised within the group on an extra field. This is not a valid bibtex field, but are essential to their working because they have ancient and essential scripts which depend on it. To handle this we can subclass the default BibTeX Export plugin and override a single method (the data mapping one). We then just call the original parent plugins mapping method to do all the heavy lifting, then just add our non-standard extra field. Total code required: less than one screen. Number of happy researchers: none (they are never satisfied), but number of researchers able to get their work done: lots. Don't believe me? [[BibTeX Extension Example|look here]]!

* See also [[Extension Packages]] for how to add configuration and resource files to plugins.

=== Types of Plugin ===

There are a number of different kinds of plugin for EPrints. You can find a comprehensive list of [[Perl_lib/EPrints/Plugin/|types of plugins here]]. The most of common of those are...

==== Export Plugin ====

These are used to export the data in a variety of formats. A number of tutorials have been created to help you create your own export plugins:

* [[Contribute:_Plugins/ExportPluginsHello| Export Plugin Tutorial 1: "Hello, World!"]]
* [[Contribute:_Plugins/ExportPluginsList| Export Plugin Tutorial 2: List handling]]
* [[Contribute:_Plugins/ExportPluginsHTML| Export Plugin Tutorial 3: HTML]]
* [[Contribute:_Plugins/ExportPluginsExcel| Export Plugin Tutorial 4: Excel]]
* [[Contribute:_Plugins/ExportPluginsZip| Export Plugin Tutorial 5: Zip]]

==== Import Plugin ====

These are used to import data into a repository. They can take datafiles directly, or they can take an ID of a record that can be retrieved in a known way, or a URL of a file, or... whatever.

These are a bit trickier to write than export plugins as parsing data is harder than just "print"ing it, but they are still reasonably straight forward. To get you started a small selection of tutorials has been written:

* [[Contribute:_Plugins/ImportPluginsCSV| Import Plugin Tutorial 1: CSV]]
* [[Contribute:_Plugins/ImportPluginsAWS| Import Plugin Tutorial 2: Amazon Web Services]]

==== Screen Plugin ====

These handle (almost) all the user interface screens. Pages like "Review" and "Profile" are just built-in plugins. You can add your own very easily.

Examples you could create...
* Birds Eye View - a view of various statistics on the database, all in one page.
* Spellchecking Tab - an additional tab in the item control page which checks the spelling on certain fields.
* Bulk Delete tool - a tool which takes a list of eprintid's and deletes them all in a fell swoop.

Look at the existing Screen Plugins for an idea of how they work. They can be very simple.

* [[How to make a Screen for the Admin Section]]
* [[How to make a Screen perform Actions]]

==== Input Component Plugin ====

These handle how the workflow components are rendered. Built in components include the default (one field) component, the multiple fields component, the upload component, the subject component (which does pretty things to a field of type "subject") and the XHTML component. You can add your own or sub-class existing ones.

==== Convert Plugin ====

These are used for two things, currently.

* Converting the full text of documents into utf-8 text for search indexing
* Converting images and pdfs into thumbnails and previews

Some examples you could create:

* RTF to utf-8 to allow rich text documents to be indexed.
* Powerpoint to Thumbnail to allow thumbnail and previews of powerpoint slides
* Video to Thumbnail/Preview to make a still preview of a video file.

== What next ==
Try out some of the examples and see where you get to. If you hit problems you can always talk to EP-Tech. {{EPrintsTech}}.

Go take a look at [[Extension Packages]] for a bit more about how you can make your plugins richer.

Its probably a good a idea to look at [[Tips to write plugins|some tips]]. It will help you write better plugins.

Probably the best place you can go is your own perl_lib/EPrints/Plugin directory and have a look at some of similar cases. Or to [http://files.eprints.org http://files.eprints.org] to take a look at other peoples plugins.

If you've written a plugin and you're happy with it the EPrints Team encourages you to share it with the EPrints community at [http://files.eprints.org http://files.eprints.org]. If nothing else its a good place to store your code for future use. You might even get some valuable feed back.

How to write plugins

2015-11-02T16:06:12Z

Dkane: /* You will need */

[[Category:Plugins]]
[[Category:Contribute]]

== What is a Plugin? ==

The plugin system for EPrints 3 has been developed to make it easy and share the most common extensions to the code without having to hack the core system (and causing yourself problems with upgrades etc.)

Plugins are a way to make functionality easy to maintain and transfer. If you make any customizations to your repository other than metadata and appearence changes then you will probably want to write a plugin.

== You will need ==
* A basic understanding of perl (don't be scared - its not hard and there's plenty of tutorials on the web)

* An EPrints installation to play about on. A Virtual box with [[:Category:Installation|EPrints installed]] is ideal.

* Information from the [[:Category:API|EPrints API]]

* For some types of plugin you might also find some Javascript and CSS knowledge helpful.

== Write a Plugin! ==

When the system loads, it automatically loads all modules in the archives/ARCHIVE_ID/cfg/plugins/EPrints/Plugin/ directory, so for simple plugins you just drop them in that directory and you're done!

When a plugin is loaded it has a registration method which is called which tells the core EPrints system what this plugin does. EPrints then makes it available as appropriate.

Clever plugins can detect features they need and adapt to use the tools available, or disable themselves if they are missing required tools (rather than crash the system). Some specialised plugins are disabled in their default state and must be enabled in the repository configuration.

Another cool thing is that plugins are Perl Objects, which means you can subclass them. Here's an real-world example: We have a research group which uses BibTeX but over the years standardised within the group on an extra field. This is not a valid bibtex field, but are essential to their working because they have ancient and essential scripts which depend on it. To handle this we can subclass the default BibTeX Export plugin and override a single method (the data mapping one). We then just call the original parent plugins mapping method to do all the heavy lifting, then just add our non-standard extra field. Total code required: less than one screen. Number of happy researchers: none (they are never satisfied), but number of researchers able to get their work done: lots. Don't believe me? [[BibTeX Extension Example|look here]]!

* See also [[Extension Packages]] for how to add configuration and resource files to plugins.

=== Types of Plugin ===

There are a number of different kinds of plugin for EPrints. You can find a comprehensive list of [[Perl_lib/EPrints/Plugin/|types of plugins here]]. The most of common of those are...

==== Export Plugin ====

These are used to export the data in a variety of formats. A number of tutorials have been created to help you create your own export plugins:

* [[Contribute:_Plugins/ExportPluginsHello| Export Plugin Tutorial 1: "Hello, World!"]]
* [[Contribute:_Plugins/ExportPluginsList| Export Plugin Tutorial 2: List handling]]
* [[Contribute:_Plugins/ExportPluginsHTML| Export Plugin Tutorial 3: HTML]]
* [[Contribute:_Plugins/ExportPluginsExcel| Export Plugin Tutorial 4: Excel]]
* [[Contribute:_Plugins/ExportPluginsZip| Export Plugin Tutorial 5: Zip]]

==== Import Plugin ====

These are used to import data into a repository. They can take datafiles directly, or they can take an ID of a record that can be retrieved in a known way, or a URL of a file, or... whatever.

These are a bit trickier to write than export plugins as parsing data is harder than just "print"ing it, but they are still reasonably straight forward. To get you started a small selection of tutorials has been written:

* [[Contribute:_Plugins/ImportPluginsCSV| Import Plugin Tutorial 1: CSV]]
* [[Contribute:_Plugins/ImportPluginsAWS| Import Plugin Tutorial 2: Amazon Web Services]]

==== Screen Plugin ====

These handle (almost) all the user interface screens. Pages like "Review" and "Profile" are just built-in plugins. You can add your own very easily.

Examples you could create...
* Birds Eye View - a view of various statistics on the database, all in one page.
* Spellchecking Tab - an additional tab in the item control page which checks the spelling on certain fields.
* Bulk Delete tool - a tool which takes a list of eprintid's and deletes them all in a fell swoop.

Look at the existing Screen Plugins for an idea of how they work. They can be very simple.

* [[How to make a Screen for the Admin Section]]
* [[How to make a Screen perform Actions]]

==== Input Component Plugin ====

These handle how the workflow components are rendered. Built in components include the default (one field) component, the multiple fields component, the upload component, the subject component (which does pretty things to a field of type "subject") and the XHTML component. You can add your own or sub-class existing ones.

==== Convert Plugin ====

These are used for two things, currently.

* Converting the full text of documents into utf-8 text for search indexing
* Converting images and pdfs into thumbnails and previews

Some examples you could create:

* RTF to utf-8 to allow rich text documents to be indexed.
* Powerpoint to Thumbnail to allow thumbnail and previews of powerpoint slides
* Video to Thumbnail/Preview to make a still preview of a video file.

== What next ==
Try out some of the examples and see where you get to. If you hit problems you can always talk to EP-Tech. {{EPrintsTech}}.

Go take a look at [[Extension Packages]] for a bit more about how you can make your plugins richer.

Its probably a good a idea to look at [[Tips to write plugins|some tips]]. It will help you write better plugins.

Probably the best place you can go is your own perl_lib/EPrints/Plugin directory and have a look at some of similar cases. Or to [http://files.eprints.org http://files.eprints.org] to take a look at other peoples plugins.

If you've written a plugin and you're happy with it the EPrints Team encourages you to share it with the EPrints community at [http://files.eprints.org http://files.eprints.org]. If nothing else its a good place to store your code for future use. You might even get some valuable feed back.

Search.pl

2012-11-15T15:57:09Z

Dkane: /* Search by Email */

==Simple Search==

$c->{search}->{simple} = {
search_fields => [
{
id => "q",
meta_fields => [
$EPrints::Utils::FULLTEXT,
"title",
"abstract",
"creators_name",
"date"
]
},
],
preamble_phrase => "cgi/search:preamble",
title_phrase => "cgi/search:simple_search",
citation => "result",
page_size => 20,
order_methods => {
"byyear" => "-date/creators_name/title",
"byyearoldest" => "date/creators_name/title",
"byname" => "creators_name/-date/title",
"bytitle" => "title/creators_name/-date"
},
default_order => "byyear",
};

==Advanced Search==

$c->{search}->{advanced} ={
search_fields => [
{ meta_fields => [ $EPrints::Utils::FULLTEXT ] },
{ meta_fields => [ "title" ] },
{ meta_fields => [ "creators_name" ] },
{ meta_fields => [ "creators_id" ] },
{ meta_fields => [ "abstract" ] },
{ meta_fields => [ "keywords" ] },
{ meta_fields => [ "subjects" ] },

{ meta_fields => [ "divisions" ] },

{ meta_fields => [ "type" ] },
{ meta_fields => [ "department" ] },
{ meta_fields => [ "editors_name" ] },
{ meta_fields => [ "ispublished" ] },
{ meta_fields => [ "refereed" ] },
{ meta_fields => [ "publication" ] },
{ meta_fields => [ "date" ] }
],
preamble_phrase => "cgi/advsearch:preamble",
title_phrase => "cgi/advsearch:adv_search",
citation => "result",
page_size => 20,
order_methods => {
"byyear" => "-date/creators_name/title",
"byyearoldest" => "date/creators_name/title",
"byname" => "creators_name/-date/title",
"bytitle" => "title/creators_name/-date"
},
default_order => "byyear",
};
=Search by Email=
Searching by email can be the best way to get publications by an individual. To add this functionality to the advanced search simply add this line:
{ meta_fields => [ "creators_id" ] },
''creators_id'' is the database column name that contains the email address.

Search.pl

2012-11-15T15:55:57Z

Dkane: /* Advanced Search */

2012-11-15T15:49:38Z

Dkane: Created page with '=Simple Search= $c->{search}->{simple} = { search_fields => [ { id => "q", meta_fields => [ …'

How to create a separate, searchable 'collection' (for eTheses)

2011-11-15T13:43:59Z

Dkane: /* Eprints 3.3x Changes to Plugin Module */

[[Category:Howto]]
==creation fo a new directory for theses==
The approach was to create new views and searches that filtered out the theses currently listed in our eprints repository and created a subfolder in the website that accessed this rather than creating a new repository just for etheses.

Here is a basic explanation:

To add new views, we modified the browse_views configuration in /cfg/cfg.d/views.pl to add the following lines:
{id=>"theses/type", allow_null=>0, fields=>"thesistype", order=>"title/authors", noindex=>0, nolink=>1 },
{id=>"theses/year", allow_null=>0, fields=>"year", subheadings=>"thesistype", order=>"title/authors", noindex=>0, nolink=>1, heading_level=>2, hideempty=>1 },
{id=>"theses/subject", allow_null=>0, fields=>"subjects", subheadings=>"thesistype", order=>"title/authors", nolink=>1, heading_level=>2, hideempty=>1},
{id=>"theses/department", allow_null=>0, fields=>"department", subheadings=>"thesistype", order=>"title/authors", noindex=>0, nolink=>1, heading_level=>2, hideempty=>1 }
''Note:'' We added the nolink option to each view so that these new views wouldn't be linked from the standard view page of the repository.

Then to add the new searches, we duplicated the configuration for the simple and advanced searches in ''/usr/share/eprints3/archives/witeprints/cfg/cfg.d/search.pl'', renaming them thesis and advthesis and added the following option to their configuration.
filters => [ { meta_fields => [ "type" ], value => "thesis" }]
We then added a new subfolder etheses in ''static/en/'' and in it created an index page for our etheses section that linked to our new views and searches.

For a consistent look we also created an ''static/en/etheses/view/'' folder and added an index that mimicked the look of the autogenerated view index of the eprints repository, except linking to our etheses views.

*Had to modify ''/usr/share/eprints3/archives/witeprints/cfg/lang/en/static/index.xpage'' , which is the main home page of the repository
*Had to modify ''/usr/share/eprints3/archives/witeprints/cfg/lang/en/static/etheses/index.xpage'' , which is the main home page of the etheses directory
*Had to modify ''/usr/share/eprints3/archives/witeprints/cfg/lang/en/templates/default.xml'', which is the main template to include links to the etheses directory on the side menu
==Eprints 3.3x Changes to Plugin Module==
The plugins module has changed things a little bit. So you have to now make an addition into the module itself.

in '''[eprints_root]/perl_lib/EPrints/Plugin/Search/Internal.pm'''

change
$self->{search} = [qw( simple/* advanced/*)];
to
$self->{search} = [qw( simple/* advanced/* thesis/* advthesis/* )];

You already should have simple, advanced, thesis, and advthesis (or whatever you call them) in '''[archive_root]/cfg/cfg.d/search.pl'''

Dkane:

In this example, we are adding a 'blog' directory, perhaps to host wordpress.

===Edit [eprint install dir]/archives/[archive]/cfg/cfg.d/[[urls.pl]]===
Amend this line to include the directory you want to make an exception for.

Here we are adding the directory /blog/ to the array.
$c->{[[rewrite_exceptions]]} = [ '/cgi/', '/archive/', ''''/blog/''''];

Save and close.

===Edit: [eprint install dir]/archives/[archive]/cfg/[[apachevhost.conf]]===

And add the following.

Alias /blog/ /path/to/blog/
<Location "/blog">
AddHandler php5-script php
DirectoryIndex index.php
</Location>
<Directory /path/to/blog>
Order allow,deny
Allow from all
</Directory>

===Restart Apache===

/etc/init.d/apache2 force-reload