Quickstart:Customise EPrints
This page assumes you have completed the previous pages in the Quickstart Guide.
What does Customise Mean in EPrints?
There are lots of ways you may want to customise EPrints, this page aims to help you understand what those ways are, and direct you to resources to help you achieve those changes.
Concepts
When changing your EPrints system, there are a few concepts its helpful to be aware of before you begin.
Archive
Your Archive is the directory created in /opt/eprints3/archives/. This holds your configuration and files that override default functionality as well as the physical location of content stored in the repository.
Phrases
Text in EPrints is designed to be customisable by admin users. To achieve this, placeholder references are included in templates which then load the content entered by an admin.
Phrases have various purposes. One is to ensure consistent use of terminology throughout the archive. It also essential for supporting multi-language archives. They are used for defining all metadata field names and their help texts.
A prominent example of a phrase is an archive's name which is appears in the archive directory's cfg/lang/en/phrases/archive_name.xml, as follows:
<epp:phrase id="archive_name">Example Archive</epp:phrase>
Citations
In EPrints repository software, a citation means something slightly different from what it means in research publication.
EPrints has files which describe how to generate the text string, not just for eprints records but also other data objects, which we refer to as 'Citation Style Files' (Citations). A data object may have different citation files for different purposes and each object may have different citation files. These files can be found under lib/citations/, flavours/pub_lib/citations/ and the archive's cfg/citations/ directory.
See here for more information about the citation formats.
Site Look and Feel
To make an EPrints Repository feel like your own, you will want to change the look and feel of different parts of the site, below we detail where different parts are controlled and link out to more in depth guides on how to achieve these customisations.
Templates
Site Templates
EPrints has 'Global' templates used to wrap page content, generally these contain your header and footer and little else (you can of course add anything you want!). There is one used for public facing pages, and one for back end pages giving the option for a different interface for admin actions. Often these two templates are identical, even symlinking one to the other.
Both templates can be found here:
/opt/eprints3/archives/ARCHIVE_ID/cfg/lang/en/templates/
(make sure to replace ARCHIVE_ID with your archive name, the name of the directory you created in /opt/eprints3/archives/)
(if they're not, copy them from /opt/eprints3/lib/templates/ into the directory above (which you may need to create))
File Names
The public template is default.xml.
The back end template is default_internal.xml.
Static Pages
Custom Files
As well as the template files, you may want to have custom CSS or Javascript that is used across the site and images included on various pages.
CSS
Your CSS styles should go in /opt/eprints3/archives/ARCHIVE_ID/cfg/static/style/auto/zzz_local.css.
You can create additional CSS files if you need.
Note: Files are loaded in alphabetical order, hence the zzz_ prefix.
Javascript
Your custom Javascript should go in /opt/eprints3/archives/ARCHIVE_ID/cfg/static/javascript/auto/90_local.js.
You can create additional .js files if you need.
Note: Files are loaded in alphabetical order, hence the 90_ prefix.
Media
Images for your site should go in /opt/eprints3/archives/ARCHIVE_ID/cfg/static/images/.
You can then load your images from http://ARCHIVE_ID.your_domain_here.net/images/EXAMPLE_IMAGE.jpg eg: https://demo.eprints-hosting.org/images/eprintslogo.png
Find Out More
You can find out more in our templating guide, Branding with Confidence
Functionality
Core Files
As a rule, to make sure you see the benefit of updates to the core codebase, you don't want to directly modify files outside of your archive directory. Instead, these files can be duplicated inside your archive and modified to allow you to make specific customisations.
Views
A View in EPrints is a page for browsing the repository, you may have a 'Browse by Author' View and/or a 'Browse by Year' View, you can have multiple Views to accomodate how your users need to access your records.
The configuration for browse views can be found in views.pl, which by default is found under /opt/eprints3/flavours/pub_lib/cfg.d/ but should be copied to the archive's cfg/cfg.d/ for editing.
See the Browse Views Category for more information.
Workflows
First class/top level data objects in EPrints (such as eprints records or users) have a workflow to allow the metadata they store to be edited via a sequence of forms.
The most common workflow is for the eprint data object. By default the configuration for this workflow is written in XML and can be found in default.xml in /opt/eprints3/flavours/pub_lib/workflows/eprint/. If this needs to be modified it should be copied to the archive's /opt/eprints3/ARCHIVE_ID/cfg/workflows/eprint/ directory before editing.
Explanation of the various elements and attributes are described in the Workflow Format Guide.
Extending
If you find youself wanting additional functionality in EPrints, you may find it's something that someone else has also needed. To allow customisations to be transferred simply between EPrints systems we have Ingredients that can be added to your system, some functionality may also only be available through the legacy EPM/Bazaar Plugins system.
Ingredients
The main purpose of ingredients is to allow complex functionality to be developed but deployed in a self contained manner, that does not impact the existing core codebase.
Typically, an ingredient would be deployed by checking out a tagged version of the Git repository for that ingredient on GitHub into the ingredients directory /opt/eprints3/ingredients/.
