EPrints Documentation - User contributions [en-gb]

How to customise thumbnails

2012-10-30T17:11:19Z

Libjlrs@leeds.ac.uk: Added categories

Based on EPrints-3.3.10.

To customise the size and type of thumbnails generated by eprints you can create archive-based configuration.
The steps below show how to add a new thumbnail size, and render it the way *I* want it.

The default thumbnails are generated by: <code>~/perl_lib/EPrints/Plugin/Convert/Thumbnails.pm</code>

I wanted to add a new size 160x90px, called 'homepage' (to fit in with the institution's branding).
To make your own set of thumbnail sizes, edit <code>~/archives/ARCHIVEID/cfg/cfg.d/plugins.pl</code>.
I added the following to the file:
<source lang="perl">
$c->{plugins}->{'Convert::Thumbnails'}->{params}->{sizes} = {(
small => [66,50],
homepage => [160, 90], # new size - others are copied from Thumbnails.pm
medium => [200,150],
preview => [400,300],
lightbox => [640,480],
)};
$c->{thumbnail_types} = sub {
my( $list, $repo, $doc ) = @_;
push @$list, qw( homepage ); # add new size to list of files to be generated
};
</source>

By default this will produce a thumbnail that will fit into a box 160x90px - a proportionally scaled down version of the original. The 'small' thumbnail size produces a cropped version of the original. This is a better option for my needs, but it has a grey 1px border around it - that I don't want.

To alter the thumbnails I need to add the following to <code>~/archives/ARCHIVEID/cfg/cfg.d/plugins.pl</code> - which is a slightly modified version of the <code>sub call_convert</code> copied from Thumbnails.pl
<source lang="perl">
$c->{plugins}->{'Convert::Thumbnails'}->{params}->{call_convert} = sub {
my( $self, $dir, $doc, $src, $geom, $size ) = @_;

my $convert = $self->{'convert'};
my $version = $self->convert_version;

if (!defined($geom)) {
EPrints::abort("NO GEOM");
}

my $fn = $size . ".jpg";
my $dst = "$dir/$fn";

$geom = "$geom->[0]x$geom->[1]";
# JPEG
# Read this: http://www.imagemagick.org/script/command-line-processing.php#geometry
# for details of the convert geom options.
#
if( $size eq "small" )
{
# attempt to create a thumbnail that fits within the given dimensions
# geom^ requires 6.3.8
if( $version > 6.3 )
{
$self->_system($convert, "-strip", "-colorspace", "RGB", "-background", "white", "-thumbnail","$geom^", "-gravity", "center", "-extent", $geom, "-bordercolor", "gray", "-border", "1x1", $src."[0]", "JPEG:$dst");
}
else
{
$self->_system($convert, "-strip", "-colorspace", "RGB", "-background", "white", "-thumbnail","$geom>", "-extract", $geom, "-bordercolor", "gray", "-border", "1x1", $src."[0]", "JPEG:$dst");
}
}
elsif( $size eq "homepage" ) # This is the new section to deal with the new 'homepage' size
{
# attempt to create a thumbnail that fits within the given dimensions
# geom^ requires 6.3.8
if( $version > 6.3 )
{
# homepage thumbnails don't want a border on them!
$self->_system($convert, "-strip", "-colorspace", "RGB", "-background", "white", "-thumbnail","$geom^", "-gravity", "center", "-extent", $geom, "-bordercolor", "white", "-border", "0x0", $src."[0]", "JPEG:$dst");
}
else
{
# homepage thumbnails don't want a border on them!
$self->_system($convert, "-strip", "-colorspace", "RGB", "-background", "white", "-thumbnail","$geom>", "-extract", $geom, "-bordercolor", "white", "-border", "0x0", $src."[0]", "JPEG:$dst");
}
}
elsif( $size eq "medium" )
{
$self->_system($convert, "-strip", "-colorspace", "RGB", "-trim", "+repage", "-size", "$geom", "-thumbnail","$geom>", "-background", "white", "-gravity", "center", "-extent", $geom, "-bordercolor", "white", "-border", "0x0", $src."[0]", "JPEG:$dst");
}
else
{
$self->_system($convert, "-strip", "-colorspace", "RGB", "-background", "white", "-thumbnail","$geom>", "-extract", $geom, "-bordercolor", "white", "-border", "0x0", $src."[0]", "JPEG:$dst");
}

if( -s $dst )
{
return ($fn);
}

return ();
};
</source>

To test the new thumbnail generation, find an eprint with some good images attached to it. In the example below I'll use '1234', and assume the original image is called 'file.jpg' and is the first docuemtn in the eprint (this only matters for the URL to view the image in the browser with).

Run <code>~/bin/epadmin/redo_thumbnails ARCHIVEID 1234 --verbose</code>

You should see the convert command being run - and the new size filename being created e.g.
<source lang="bash">
Starting EPrints Repository.
Connecting to DB ... done.
Redoing thumbnails for document 1234
/usr/bin/convert -strip -colorspace RGB -background white -thumbnail 160x90^ -gravity center -extent 160x90 -bordercolor white -border 0x0 /opt/eprints3/archives/digitallibrary/documents/disk0/00/00/12/34/01/file.jpg[0] JPEG:/tmp/_NyUoqmsuZ/homepage.jpg
/usr/bin/convert ... JPEG:/tmp/XR51ieKBCj/lightbox.jpg
/usr/bin/convert ... JPEG:/tmp/fCOP2BPoa2/preview.jpg
/usr/bin/convert ... JPEG:/tmp/zLEip1ewUq/medium.jpg
/usr/bin/convert ... JPEG:/tmp/weRJwQPgNT/small.jpg
</source>
NB The lines for lightbox, preview, medium and small.jpg have been truncated for clarity.

You should new be able to view the new thumbnails in a browser:
<code><nowiki>http://your.repo.url/1234/1.hashomepageThumbnailVersion/file.jpg</nowiki></code>

[[Category:Howto]][[Category:Snippets]][[Category:Contribute]]

2012-10-04T09:33:05Z

Libjlrs@leeds.ac.uk:

{{formats}}

'''NOTE:''' There are many functions not documented on this page. Look in ~/perl_lib/EPrints/Script/Compiled.pm for other functions.

This is an introduction.

= Language Synopsis =

$var{xxx} - get the value of 'xxx' in $var

$var{xxx}{yyy} - get the value of 'yyy' in 'xxx' in $var

$var.xxx(yyy) - call method 'xxx' on $var with argument 'yyy'

xxx(yyy) - call method 'xxx' with argument 'yyy'

xxx - get the value of field 'xxx'

xxx OP yyy - test whether 'xxx' is OP 'yyy' (=, !=, etc.)

xxx LOGIC yyy - test whether 'xxx' LOGIC 'yyy' (and, or, not etc.)

== Examples ==

$config{oai}{v2}{archive_id} - gets the current OAI repository identifier

$current_user{department}.is_set() - returns true if the user's department field is set

published.one_of('submitted','published') - returns true if published is 'unpub' or 'published'

$item{type} = 'patent' - returns true if type from item is 'patent'

join($item{userid}.as_item(){collection},',') - useful for extracting data in 'multiple' fields. For the owner of the eprint, return all 'collection's as a comma-separated string.

= Global Variables =

$config{xxx} - a value from the configuration.

$current_user - the current user, e.g., $current_user{username}

$current_lang - the id of the current language (such as 'en')

$item - the current item (usually an eprint, but not always, e.g., in citations or workflows for user objects), e.g., $item{eprintid}. If you just use '''eprintid''' it is a shortcut for '''$item{eprintid}'''

= Data Types =

EPScript allows for two primitive data types (string and integer) as well as providing the means to access properties of data objects such as EPrints or Users.

== Primitive Types ==

=== Strings and characters ===

These are contained within either double quotes ("") or single quotes (<nowiki>''</nowiki>). There is no difference between the two, but it may be easier to use one sort when inside an XML attribute. For example:

<when test="type = 'patent'">
...
</when>

=== Integers ===

Integers are defined as a string of numbers from 0-9, e.g. 300. Leading zeros do not have any effect, and decimal values are currently not supported.

=== Booleans ===

True or false values. Returned by = gt and lt and oneof and used in <if> etc.

== Data Objects ==

Data Objects include most of the key EPrints objects - whether an EPrint itself, documents related to the EPrint, or a user. EPScript treats all of these data objects the same, with a simple approach to retrieve properties. When an EPScript is executed, an 'item' object is supplied. In the case of a citation file, this will be the item for which the citation is being created. For a workflow, this will be the object on which the workflow acts (e.g. an EPrint or a user). Properties of main objects can be accessed using a shortened approach - the following example is from a user workflow, so the usertype property is available:

<if test="usertype = 'editor'">
...
</if>

There are cases, however, where two or more data objects may be provided - such as an EPrint and a user. Here the main item can still be accessed in the short form, but other objects use a dollar notation. In this example, the EPrint is available as $eprint:

<if test="$eprint{ispublished}.one_of('unpub', 'submitted', 'inpress')"> (<print expr="$eprint{ispublished}" />)</if>

== Field Values ==

Values associated with a data object field. The field which the value belongs to can effect how it is rendered, and compared to other values.

== Hash ==

This currently only used by the $config parameter to give access to configuration options. Get values out of it the same way you get values from a dataobejct, eg. $config{'base_url'}

== XHTML ==

The citation method returns a pre-rendered value. You can't do anything with XHTML other than print it.

= Operators =

==Logical Operators==

===and===

Returns true if both the left-hand and the right-hand expressions return true.

<if test="type = 'book' and is_set( creators )">
...
</if>

===or===
Returns true if at least one of the expressions returns true.

<if test="type = 'book' or type = 'patent'">
...
</if>

===not===
Returns true if the expression is false and false if the expression is true.

<if test="!is_set( creators )">
...
</if>

==Comparison Operators==

===lt===

Returns true if the left-hand expression is less than the right-hand expression. This is only applicable to expressions that return numeric values.

<if test="length(editors) lt 6">
...
</if>

===gt===

Returns true if the left-hand expression is greater than the right-hand expression. This is only applicable to expressions that return numeric values.

<if test="length(editors) gt 1">
...
</if>

===equals===

Returns true if the left-hand expression is equal to the right-hand expression. This applies to numeric, boolean, and string values.

<if test="type = 'patent'">
...
</if>

If the left OR the right value is a FIELDVALUE of a multiple field, then it returns true if the other value matches any of the values on the other side. eg. "subjects = 'group_foo'" will be true if any of the subjects are "group_foo".

===not equals===

The inverse of the equals operator, this returns true if the expressions are not equal.

<if test="type != 'book'">
...
</if>

= Functions =

== Calling Functions ==

Functions can be called in two ways:

<when test="is_set( creators )">

<print expr="citation( eprint,title )">

or

<when test="creators.is_set()">

<print expr="eprint.citation( title )">

These are interchangable, but it may be beneficial to use a specific form in some cases.

== Function List ==

=== is_set ===

Returns true if the parameter is set, based on the following criteria:
* If the parameter is a string, it is set if it is not empty.
* If the parameter is a list or a complex structure, it is set if at least one value is set.

<when test="is_set( creators )">
...
</when>

parameters: is_set(ANYTHING)

returns: BOOLEAN

=== length ===

Returns the number of items in the list.

<if test="length(editors) gt 1">s</if>

parameters: length(ANYTHING) .. although only Field Values make much sense

returns: INTEGER

=== one_of ===

Returns true if the string is in the list of strings provided.

<when test="type.one_of( 'book','book_section' )">
...
</when>

Can in theory use any type of value. Will use the "=" method to compare them.

parameters: ANYTHING.one_of( LIST )

returns: BOOLEAN

=== reverse ===

Returns the reverse of a string (i.e. 'abc' becomes 'cba').

<when test="type.reverse = 'tnetap'">
...
</when>

This function was largely used for debugging, it's not very useful...

parameters: reverse(STRING)

returns: STRING

=== yesno ===

Returns a string "yes" or "no" depending on the value of the boolean passed to it.

parameters: yesno(BOOLEAN)

returns: STRING

=== citation ===

Can only be called on a dataobject. eg. $item or $current_user. It returns the object rendered using the specified citation style.

<epc:print expr="$item.citation('default')" />

The results of citation are only really useful for rendering, not testing.

parameters: DATAOBJ.citation(STRING)

returns: XHTML data

=== as_item ===

A very useful little method. This can only be called on a field value of a field of type "itemref". It returns the item itself.

<epc:print expr="$item{userid}.as_item(){username}" />

parameters: FIELDVALUE.as_item()

returns: DATAOBJECT

= Examples =

== Pluralising the editors of a book ==

<if test="type = 'book' and is_set(editors)">
<print expr="editors" />, (ed<if test="length(editors) gt 1">s</if>
</if>

== Rendering the URL of an EPrint ==

<print expr="$config{base_url}" />/<print expr="eprintid" />/

Recaptcha

2012-10-02T14:27:43Z

Libjlrs@leeds.ac.uk: Added categories

NOTE: This has been written based on my experience of an EPrints 3.3.10 install.

== Configuring reCAPTCHA for user registration ==
Recent versions of EPrints (3.2+?) have configuration that allows reCAPTCHA to be used for user registration and/or document requests.
If your version of EPrints has the file: ~/perl_lib/EPrints/MetaField/Recaptcha.pm, these instructions *should* work...

== What to do ==
# Register for a reCAPTCHA key at http://www.google.com/recaptcha (Click on the 'Use reCAPTCHA on your site' link).
# Add reCAPTCHA keys to config
# Configure a field to use reCAPTCHA
# Add field to workflow

== Adding the config ==
Create a file: ~/archives/ARCHIVEID/cfg/cfg.d/recaptcha.pl
<source lang="perl">
# Used by recaptcha fields. See ~/perl_lib/EPrints/MetaField/Recaptcha.pm
# Captcha registered by you@your-institution
$c->{recaptcha}->{public_key} = "...";
$c->{recaptcha}->{private_key} = "...";
</source>
Add the keys you got when registering for reCAPTCHA.

''You can create either domain specific keys, or general purpose keys. If you run multiple archives you might want to create general keys and add the config file to ~/lib/cfg.d/ instead.''

== Adding reCAPTCHA to User Registration ==
First we have to add the reCAPTCHA field to the user config.
I added the following code to the end of my recaptcha.pl file, but you could also add the field definition directly to the 'user_fields.pl' file.
<source lang="perl">
#Add field to user dataset
$c->add_dataset_field( "user", {
name => "captcha",
type => "recaptcha",
});
</source>
Now reload the configuration and update the database (through the web interface Admin->Config. Tools -> Reload Config / Update Database) - or via the command line.

Next, we have to add the field to the user registration workflow. If you haven't edited the registration workflow, look at ~/lib/workflows/user/register.xml. Add the following component after the existing Field::Multi component.
<source lang="xml">
<component surround="None"><field ref="captcha" /></component>
</source>
''If you are running multiple archives and some need reCAPTCHA and others don't, copy the register.pl file into ~/archives/ARCHIVEID/workflows/user/ and edit it there.''

Reload the configuration again, and then visit your 'Create Account' page - you should have a nice shiny reCAPTCHA added to the registration!

== Adding reCAPTCHA to Document requests==
This is similar to the above, basically add a field to the request dataset, render it in the workflow (did you know that requests now have a workflow? I didn't!).

Add the following to recaptcha.pl - or another suitable cfg.d/...pl file:
<source lang="perl">
#Add field to requests
$c->add_dataset_field( "request", {
name => "captcha",
type => "recaptcha",
});
</source>

Add the field to the workflow for requests ~/lib/workflows/request/default.xml
<source lang="xml">
<component surround="None"><field ref="captcha" /></component>
</source>
Reload config, update database etc. and test it works!

Good work EPrints developers - it took about 10 minutes to get it working (and about 30 minutes to write this page :o)!

[[Category:Howto]][[Category:Snippets]][[Category:Metadata Fields]][[Category:Contribute]]

2012-06-28T14:39:27Z

Libjlrs@leeds.ac.uk: added 'in practice' section

The British Library EThOS service has a SOAP based webservice to allow institutions to pull digitized theses back from their collection.
The code uses:
* SOAP::Lite (to make the calls to the webservice)
* LWP (to download the Zip files)
* Archive::Zip (to extract the files)
* Time::Local (to generate timestamps for the webservice)

The code consists of two parts:
* a bin script (goes in ~/bin/)
* a config file (goes in ~/archives/ARCHIVEID/cfg/cfg.d/)

Run ~/bin/ethos to see usage

The following rules are used:
1) If an incoming thesis contains an institutionalReference (therefore has been harvested):
* A search is done on the reference
** If the eprint doesn't exist, no import is done.
** If the eprint exists and doesn't have an id_number, the id_number is added.
** If the eprint exists and the id_number matches the ethosId no import is done.
** If the eprint exists and the id_number doesn't match the ethosId, an error is reported.

2) If the incoming thesis does not have an institutionalReference, a search for the ethosId in the id_number field is conducted.
* If an eprint exists with that ethosId, no import is done.
* If the ethosId is not found, a new eprint is created. Files are downloaded, and added to the eprint. Any issues with the download are recorded in the 'suggestions' field.

The following fields are set in the EPrint:
* userid
* title
* date
* abstract
* id_number
* keywords
* creators_name
* thesis_type
* suggestions

The scripts were written based on the White Rose Etheses Online set up. This means the config file may seem a bit warped in it's structure - as it was designed to be able to cope with 3 institutions.

== EThOS Identifiers ==
EThOS identifiers are of the form: '''uk.bl.ethos.''xxxxx'''''.
If you have ethos identifiers stored in your system in a different format, you will need to tweak the code to cope with your way of storing them.
Any question/problems with the script, email the tech-list!

== Downloading EThOS records in practice ==
The process of dealing with etheses the three White Rose institutions is different at each site.
In general though, there is a different route and set of people dealing with theses coming from EThOS to those being deposited by students as part of teir studies.
We have created an 'EThOS import' user for each site, and provided a custom workflow for these users.
There are fewer 'required' metadata elements for EThOS theses - we don't have a record of any 'supervisor email address' for a 1956 thesis!

Files/EThOS webservice download tool

2012-06-28T14:24:47Z

Libjlrs@leeds.ac.uk: Added EThOS identifiers note

Files/EThOS webservice download tool

2012-06-28T14:18:47Z

Libjlrs@leeds.ac.uk:

Files/EThOS webservice download tool

2012-06-28T13:59:36Z

Libjlrs@leeds.ac.uk: Created page with 'The British Library EThOS service has a SOAP based webservice to allow institutions to pull digitized theses back from their collection. The code uses: * SOAP::Lite (to make the …'

Files/CoverPDF

2010-12-23T13:59:24Z

Libjlrs@leeds.ac.uk: /* pdftk */

[[Category:EPrints 3 Plugins]]
An EPrints extension to automatically generate cover pages for PDF documents.

==Prerequisites==

===pdflatex===

The LaTeX front end for the TeX text formatting system
http://www.tug.org/texlive/

yum install texlive-latex (Fedora 10)

Note older distros may still be using tetex packages http://www.tug.org/tetex/

===pdftk===

The PDF Tool Kit
http://www.accesspdf.com/pdftk/
(2010-12-23 pdftk can now be found here: http://www.pdflabs.com/docs/install-pdftk/ )
yum install pdftk (Fedora 10)

==Installation (EPrints 3.1+)==

Download the latest tarball to your local repository directory (eg. /opt/eprints3/archives/ARCHIVEID/)

Extract files:

tar xzvf coverpdf_install_xx.tgz

The following files should be extracted:

===cfg/cfg.d/coverpage.pl===

Allows you to configure which cover page gets applied to which document. For example you might like to use a single coverpage for all PDF documents, only apply the cover page to certain types of PDF document (eg. articles), or use different cover pages for different types of PDF document.

The default is to apply a single coverpage (defined in coverpage.xml - see below) to all PDF documents.

'''Note: check that the pdflatex and pdftk paths are correct for your system.

===cfg/lang/en/phrases/coverpage.xml===

Defines cover page template(s) which you can adjust to change the content and/or appearance of your cover page(s). Each cover page is defined as a LaTeX template which can include information about the repository (eg. repository name, admin email address) and metadata about the document (eg. citation, URL).

The default cover page template displays the repository logo and lists the document citation and URL. A brief "Usage Guidelines" section is also included.

'''Note: gif format logos are not supported by pdflatex - see Troubleshooting section below.

===cfg/plugins/EPrints/Plugin/Convert/CoverPDF.pm===

Conversion plugin which actually does the work of creating the cover page and prepending it to a PDF document.

'''Note: the original PDF document is never overwritten - the conversion plugin makes a separate copy with a cover page.

==Getting Started==

To activate cover pages, you need to make a small change to the EPrints/Apache/Rewrite.pm module.

vim /opt/eprints3/perl_lib/EPrints/Apache/Rewrite.pm

Around line 182 find the following code:

# let it fail if this isn't a real eprint
if( !defined $eprint )
{
$session->terminate;
return OK;
}

Add the following immediately after:

if( !$thumbnails && $session->get_repository->can_call( "coverpage", "process_request" ) )
{
my $ret = $session->get_repository->call( [ "coverpage", "process_request" ], $session, $r, $eprint, $pos, $tail );
return $ret if defined $ret;
}

This gives the coverpage extension a chance to look at the request and decide whether a cover page needs to be generated.

Save the file and restart Apache.

You should now find that all PDF documents in your repository have a cover page. If you change the layout or content of the cover page (by editing coverpage.xml), all cover pages should automatically be updated to reflect the change. Also, if the metadata of the record changes the cover page should also automatically update to reflect the new metadata.

==Troubleshooting==

===GIF image not appearing on cover page===

pdflatex does not support gif images - convert the gif image to a supported format such as png.

The default cover page uses the site_logo setting defined in cfg.d/branding.pl. By default the logo is a gif image:

$c->{site_logo} = "/images/sitelogo.gif";

To create a png version of the logo:

cd /opt/eprints3/archives/ARCHIVEID/cfg/static/images/
convert sitelogo.gif sitelogo.png

Edit branding.pl and change sitelogo.gif to sitelogo.png.

"Touch" coverpage.xml so that cover pages will be regenerated:

touch /opt/eprints3/archives/ARCHIVEID/cfg/lang/en/phrases/coverpage.xml

The logo should now appear on the cover page.

==="Check that coverpage content is valid LaTeX" error message in log===

This can sometimes appear after touching/editing coverpage.xml even if the LaTeX code is correct. Restart Apache and try again.

Check for any mktexfmt error messages in the log - see below.

If the problem persists, try running pdflatex against the cover page template manually:

cd /tmp
mkdir coverpage-test
cd coverpage-test
vi cover.tex
(copy LaTeX code from coverpage.xml into cover.tex)
pdflatex cover.tex

Examine the pdflatex output for errors.

This problem can also appear because of an intermittent bug in pdflatex. The symptom is that cover pages generally work, but occasionally (and transiently) either fail to appear or, more rarely, cause an internal server error. In this case, a workaround is to use latex and dvipdf instead of pdflatex. A (clumsy) way to do this is to modify CoverPDF.pm, replacing the line

system( $pdflatex, "-interaction=nonstopmode", "-output-directory=$latex_dir", $latex_file );

with

system( "latex", "-interaction=nonstopmode", "-output-directory=$latex_dir", $latex_file );
system( "cd $latex_dir && dvipdf cover.dvi" );

==="fmtutil: format directory does not exist" error message in log===

Full error message:

kpathsea: Running mktexfmt pdflatex.fmt
fmtutil: format directory `/.texlive2007/texmf-var/web2c' does not exist.

Some texlive packages do not include all the necessary TeX format files to run. To generate the missing files, run the following as the "eprints" user (or the user you configured EPrints to run as):

fmtutil --missing

Under Fedora 10, the home directory seen by the EPrints web server differs from that of the eprints user, so as root you may need to do

mkdir /.texlive2007
chown eprints.eprints /.texlive2007
chmod g+w /.texlive2007

and then as the eprints user

HOME=/ fmtutil --missing

===Encrypted PDFs / "Check the PDF is not password-protected" error message in log===

If a PDF document is encrypted (password protected), a cover page cannot be added.

To check for encrypted PDFs during the deposit process (and display a '''warning''' message) add the following to cfg.d/eprint_warnings.pl:

foreach my $doc ( @docs )
{
if( $doc->get_type eq 'application/pdf' )
{
use PDF::API2;
my $pdf = PDF::API2->open( $doc->local_path.'/'.$doc->get_main );
if( defined $pdf && $pdf->isEncrypted )
{
my $fieldname = $session->make_element( "span", class=>"ep_problem_field:documents" );
push @problems, $session->html_phrase( "validate:encrypted_pdf", fieldname => $fieldname );
}
}
}

'''Note: You will need to install the PDF::API2 Perl module.

'''Hint: If you want to prevent depositors from submitting encrypted PDFs, adapt the code to cfg.d/eprint_validate.pl instead.

===Ampersands and other characters do not render correctly on cover sheet===

Some characters, such as ampersands and copyright symbols, need to be quoted to render correctly in LaTeX. Try adding the following local subroutine to $coverpage->{getcontent}:

$coverpage->{get_content} = sub {
[...]
my $latex_encode = sub {
my ($string) = @_;
utf8::decode($string);
return TeX::Encode::encode( "latex", $string );
};
[...]
};

You can then use &$latex_encode() to wrapper the strings in %bits:

my %bits = (
citation => &$latex_encode( EPrints::Utils::tree_to_utf8( $eprint->render_citation() ) ),
[...]
);

===Older versions of pdflatex do not support -output-directory===

Error messages in the log like:

/usr/bin/pdflatex: unrecognized option `-output-directory=/tmp/1cS5K8nVch'

In CoverPDF.pm, try replacing:

system( $pdflatex, "-interaction=nonstopmode", "-output-directory=$latex_dir", $latex_file );

with:

use Cwd;
my $prev_dir = getcwd;
chdir( $latex_dir );
system( $pdflatex, "-interaction=nonstopmode", $latex_file );
chdir( $prev_dir );

Files/CoverPDF

2010-12-23T13:57:40Z

Libjlrs@leeds.ac.uk: /* pdftk */

[[Category:EPrints 3 Plugins]]
An EPrints extension to automatically generate cover pages for PDF documents.

==Prerequisites==

===pdflatex===

The LaTeX front end for the TeX text formatting system
http://www.tug.org/texlive/

yum install texlive-latex (Fedora 10)

Note older distros may still be using tetex packages http://www.tug.org/tetex/

===pdftk===

The PDF Tool Kit
http://www.accesspdf.com/pdftk/
(2010-12-23 pdftk can not be found here: http://www.pdflabs.com/docs/install-pdftk/ )
yum install pdftk (Fedora 10)

==Installation (EPrints 3.1+)==

Download the latest tarball to your local repository directory (eg. /opt/eprints3/archives/ARCHIVEID/)

Extract files:

tar xzvf coverpdf_install_xx.tgz

The following files should be extracted:

===cfg/cfg.d/coverpage.pl===

Allows you to configure which cover page gets applied to which document. For example you might like to use a single coverpage for all PDF documents, only apply the cover page to certain types of PDF document (eg. articles), or use different cover pages for different types of PDF document.

The default is to apply a single coverpage (defined in coverpage.xml - see below) to all PDF documents.

'''Note: check that the pdflatex and pdftk paths are correct for your system.

===cfg/lang/en/phrases/coverpage.xml===

Defines cover page template(s) which you can adjust to change the content and/or appearance of your cover page(s). Each cover page is defined as a LaTeX template which can include information about the repository (eg. repository name, admin email address) and metadata about the document (eg. citation, URL).

The default cover page template displays the repository logo and lists the document citation and URL. A brief "Usage Guidelines" section is also included.

'''Note: gif format logos are not supported by pdflatex - see Troubleshooting section below.

===cfg/plugins/EPrints/Plugin/Convert/CoverPDF.pm===

Conversion plugin which actually does the work of creating the cover page and prepending it to a PDF document.

'''Note: the original PDF document is never overwritten - the conversion plugin makes a separate copy with a cover page.

==Getting Started==

To activate cover pages, you need to make a small change to the EPrints/Apache/Rewrite.pm module.

vim /opt/eprints3/perl_lib/EPrints/Apache/Rewrite.pm

Around line 182 find the following code:

# let it fail if this isn't a real eprint
if( !defined $eprint )
{
$session->terminate;
return OK;
}

Add the following immediately after:

if( !$thumbnails && $session->get_repository->can_call( "coverpage", "process_request" ) )
{
my $ret = $session->get_repository->call( [ "coverpage", "process_request" ], $session, $r, $eprint, $pos, $tail );
return $ret if defined $ret;
}

This gives the coverpage extension a chance to look at the request and decide whether a cover page needs to be generated.

Save the file and restart Apache.

You should now find that all PDF documents in your repository have a cover page. If you change the layout or content of the cover page (by editing coverpage.xml), all cover pages should automatically be updated to reflect the change. Also, if the metadata of the record changes the cover page should also automatically update to reflect the new metadata.

==Troubleshooting==

===GIF image not appearing on cover page===

pdflatex does not support gif images - convert the gif image to a supported format such as png.

The default cover page uses the site_logo setting defined in cfg.d/branding.pl. By default the logo is a gif image:

$c->{site_logo} = "/images/sitelogo.gif";

To create a png version of the logo:

cd /opt/eprints3/archives/ARCHIVEID/cfg/static/images/
convert sitelogo.gif sitelogo.png

Edit branding.pl and change sitelogo.gif to sitelogo.png.

"Touch" coverpage.xml so that cover pages will be regenerated:

touch /opt/eprints3/archives/ARCHIVEID/cfg/lang/en/phrases/coverpage.xml

The logo should now appear on the cover page.

==="Check that coverpage content is valid LaTeX" error message in log===

This can sometimes appear after touching/editing coverpage.xml even if the LaTeX code is correct. Restart Apache and try again.

Check for any mktexfmt error messages in the log - see below.

If the problem persists, try running pdflatex against the cover page template manually:

cd /tmp
mkdir coverpage-test
cd coverpage-test
vi cover.tex
(copy LaTeX code from coverpage.xml into cover.tex)
pdflatex cover.tex

Examine the pdflatex output for errors.

This problem can also appear because of an intermittent bug in pdflatex. The symptom is that cover pages generally work, but occasionally (and transiently) either fail to appear or, more rarely, cause an internal server error. In this case, a workaround is to use latex and dvipdf instead of pdflatex. A (clumsy) way to do this is to modify CoverPDF.pm, replacing the line

system( $pdflatex, "-interaction=nonstopmode", "-output-directory=$latex_dir", $latex_file );

with

system( "latex", "-interaction=nonstopmode", "-output-directory=$latex_dir", $latex_file );
system( "cd $latex_dir && dvipdf cover.dvi" );

==="fmtutil: format directory does not exist" error message in log===

Full error message:

kpathsea: Running mktexfmt pdflatex.fmt
fmtutil: format directory `/.texlive2007/texmf-var/web2c' does not exist.

Some texlive packages do not include all the necessary TeX format files to run. To generate the missing files, run the following as the "eprints" user (or the user you configured EPrints to run as):

fmtutil --missing

Under Fedora 10, the home directory seen by the EPrints web server differs from that of the eprints user, so as root you may need to do

mkdir /.texlive2007
chown eprints.eprints /.texlive2007
chmod g+w /.texlive2007

and then as the eprints user

HOME=/ fmtutil --missing

===Encrypted PDFs / "Check the PDF is not password-protected" error message in log===

If a PDF document is encrypted (password protected), a cover page cannot be added.

To check for encrypted PDFs during the deposit process (and display a '''warning''' message) add the following to cfg.d/eprint_warnings.pl:

foreach my $doc ( @docs )
{
if( $doc->get_type eq 'application/pdf' )
{
use PDF::API2;
my $pdf = PDF::API2->open( $doc->local_path.'/'.$doc->get_main );
if( defined $pdf && $pdf->isEncrypted )
{
my $fieldname = $session->make_element( "span", class=>"ep_problem_field:documents" );
push @problems, $session->html_phrase( "validate:encrypted_pdf", fieldname => $fieldname );
}
}
}

'''Note: You will need to install the PDF::API2 Perl module.

'''Hint: If you want to prevent depositors from submitting encrypted PDFs, adapt the code to cfg.d/eprint_validate.pl instead.

===Ampersands and other characters do not render correctly on cover sheet===

Some characters, such as ampersands and copyright symbols, need to be quoted to render correctly in LaTeX. Try adding the following local subroutine to $coverpage->{getcontent}:

$coverpage->{get_content} = sub {
[...]
my $latex_encode = sub {
my ($string) = @_;
utf8::decode($string);
return TeX::Encode::encode( "latex", $string );
};
[...]
};

You can then use &$latex_encode() to wrapper the strings in %bits:

my %bits = (
citation => &$latex_encode( EPrints::Utils::tree_to_utf8( $eprint->render_citation() ) ),
[...]
);

===Older versions of pdflatex do not support -output-directory===

Error messages in the log like:

/usr/bin/pdflatex: unrecognized option `-output-directory=/tmp/1cS5K8nVch'

In CoverPDF.pm, try replacing:

system( $pdflatex, "-interaction=nonstopmode", "-output-directory=$latex_dir", $latex_file );

with:

use Cwd;
my $prev_dir = getcwd;
chdir( $latex_dir );
system( $pdflatex, "-interaction=nonstopmode", $latex_file );
chdir( $prev_dir );

Find creation date of cache tables

2010-12-22T12:16:04Z

Libjlrs@leeds.ac.uk:

To see the date that your cache tables were created, use the following MySQL comment (run as a 'powerful' mysql user):

mysql> select TABLE_SCHEMA, TABLE_NAME, CREATE_TIME from information_schema.tables WHERE TABLE_NAME RLIKE 'cache[0-9]';
[[Category:Snippets]]

2010-10-18T11:01:23Z

Libjlrs@leeds.ac.uk: new page

[[Category:Plugins]]
To change the functionality of a core plugin within a specific archive, you can make a subclass of the original package.

Make a directory (in this example I'm subclassing a Screen plugin):
~/archives/ARCHIVEID/cfg/plugins/EPrints/Plugins/Screen

copy the original plugin to this location, with a new name:
cp ~/perl_lib/EPrints/Plugin/Screen/Items.pm ~/archives/ARCHIVEID/cfg/plugins/EPrints/Plugins/Screen/MyItems.pm

From the file, remove any subs that you don't need, and rename the package according to the name of the new file (in this example, I'm only redefining the 'render' sub).
The file should look a bit like this:
package EPrints::Plugin::Screen::MyItems;
@ISA = qw/ EPrints::Plugin::Screen::Items /;

use strict;

sub render
{
my( $self ) = @_;
my $session = $self->{session};
...
...
} #end of sub render

Tips to write plugins

2010-10-18T10:49:25Z

Libjlrs@leeds.ac.uk: added link to new instructrions page

[[Category:Plugins]]
I've written a lot of plugins for EPrints 3+ now and so i think its time to share the knowledge. If you care you can read about the mess I got into in the early days [http://blogs.ecs.soton.ac.uk/oneshare/2009/09/25/taking-stock-and-mopping-up-the-mess-i-made-of-eprints/ here].

So without further ado let me give you the top 10 ways to avoid making a hash of your EPrints install when doing a large customization:

* Rule 1: NEVER edit Session.pm if there is one file that you will absolutely not recover from it’s this. also there is an easy way to avoid editing it see rule 6.

* Rule 2: Don’t edit anything in perl_lib/EPrints. Make copies with a new name and new package. That way these files wont be over written when you upgrade.

* Rule 3: Everything in the Plugin/ directory which you do should be kept in the appropiate place in archives/YOUR_REPOSITORY/cfg/plugins/EPrints/Plugin etc. This is a really good way to keep track of what you’ve actually done.

* Rule 4: Everything you do should be a plugin. EPrints has plugins for almost everything which means you should be able to do almost all funtionality in plugins. See [[Instructions for local plugins]]

* Rule 5: For everything you want to do which doesn't seem to be a plugin think really hard. Are you SURE it’s not a plugin? Really SURE? Are you SURE you need this functionality? Really SURE?

* Rule 6: If you have followed rule 5 and you are still really sure then kludge a plugin, a kuldgin as I like to call them, using namespace over writing. This is feature/artifact of perl, from one package you can write in another package. Add methods to the DataObj::EPrint good example of where you might want to do this. To do it :

make a Plugin (yes a plugin) in your local cfg (see rule 3). start the plugin file in the normal way:
package EPrints::Plugin::MyPlugin;
use strict;
our @ISA = qw/ EPrints::Plugin /;
#now for the clever bit
package EPrints::DataObj::EPrint;
sub mysubroutine{
return(”foo”);
}

That has added mysubroutine to DataObj::EPrint so you can now

my $eprint = EPrint::DataObj::EPrint->new($session, 23); #get eprint 23
print $eprint->mysubroutine(); #prints “foo”

* Rule 7: learn about cfg/cfg.d/plugins.pl. This file lets you disable plugins you dont want to use or map you modified plugins over other plugins. For example use MyReview.pm everywhere you would usually use Review.pm – very powerful. It also lets you define where plugins apear around about the place.

* Rule 8: for plugins which use a cgi script for whatever reason (usually ajax) make a directory in cgi which has the same name as the plugin for example cgi/myfirstplugin where all the cgi used by MyFirstPlugin.pm can be found. It makes it much easier to see what youve done and if you want to deploy the plugin somewhere else you grab the plugin file and the directory and you well on the way.

* Rule 9: Give each plugin its own phrase file. I got into a hidious mess where my zz_local.xml phrase file was about a 4000 lines long and it wasnt clear what phrases belonged to what plugin.

* Rule 10: If your plugin needs configuring put all the config options in a cfg/cfg.d/my_plugins_config_options.pl that way the user only has to go to one place edit the options and different repositories using the same plugin can have different options.

In conclusion obey rules 1-10. If I’d known this stuff when I’d started we probably wouldnt have needed the first 6 months of the OneShare project.