Difference between revisions of "Quickstart:Customise EPrints"
(→Phrases) |
(→Re-Generate Pages) |
||
| (71 intermediate revisions by the same user not shown) | |||
| Line 10: | Line 10: | ||
<p>Your Archive is the directory created in <code>/opt/eprints3/archives/</code>. This holds your configuration and files that override default functionality as well as the physical location of content stored in the repository.</p> | <p>Your Archive is the directory created in <code>/opt/eprints3/archives/</code>. This holds your configuration and files that override default functionality as well as the physical location of content stored in the repository.</p> | ||
==== Phrases ==== | ==== Phrases ==== | ||
| − | <p>Text in EPrints is designed to be customisable by admin users | + | <p>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.</p> |
<p>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.</p> | <p>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.</p> | ||
<p>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:</p> | <p>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:</p> | ||
| Line 16: | Line 16: | ||
==== Citations ==== | ==== Citations ==== | ||
| + | In [[EPrints_Glossary#EPrints repository software|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' (<i>Citations</i>). 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 <code>cfg/citations/</code> directory. | |
| − | === Templates === | + | <i>See here for more information about the [[Citation Format|citation formats]].</i> |
| + | |||
| + | = 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. | ||
| + | |||
| + | <p>Both templates can be found here:</p> | ||
| + | <code> /opt/eprints3/archives/ARCHIVE_ID/cfg/lang/en/templates/</code> | ||
| + | <p><i>(make sure to replace <code>ARCHIVE_ID</code> with your archive name, the name of the directory you created in <code>/opt/eprints3/archives/</code>)</i><br/></p> | ||
| + | <p><i>(if they're not, copy them from <code>/opt/eprints3/lib/templates/</code> into the directory above (which you may need to create))</i></p> | ||
| + | |||
| + | ==== File Names ==== | ||
| + | <p>The public template is <code>default.xml</code>.</p> | ||
| + | |||
| + | <p>The back end template is <code>default_internal.xml</code>.</p> | ||
| + | |||
| + | ==== Re-Generate Pages ==== | ||
| + | <p>After updating your global template you will need to run</p> | ||
| + | /opt/eprints3/bin/generate_static ARCHIVE_ID | ||
| + | /opt/eprints3/bin/generate_views ARCHIVE_ID | ||
| + | /opt/eprints3/bin/generate_abstracts ARCHIVE_ID | ||
| + | <p>to regenerate the pages across the site.</p> | ||
| + | |||
| + | === Static Pages === | ||
| + | <p>Static pages use the global templates (see [#Site_Templates |above]) as a wrapper for the content they contain. The content can be modified by editing the relevant file, the most prominant static page is the homepage, the template file for it is <code>index.xpage</code> and can be found at <code>/opt/eprints3/lib/themes/example/lang/en/static/index.xpage</code>. It should be copied to <code>/opt/eprints3/archives/ARCHIVE_ID/cfg/lang/en/static/</code> before being modified. Additional templates can be created in the same archive level <code>/static</code> directory for other pages.</p> | ||
| + | ==== Re-Generate Pages ==== | ||
| + | <p>After updating your template you will need to run <code>/opt/eprints3/bin/generate_static ARCHIVE_ID</code> to regenerate the pages</p> | ||
| + | ==== Find out More ==== | ||
| + | <p>Find out more about static pages [[How_to_modify_static_pages | here]].</p> | ||
=== Custom Files === | === Custom Files === | ||
| + | <p>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.</p> | ||
| + | ==== CSS ==== | ||
| + | <p>Your CSS styles should go in <code>/opt/eprints3/archives/ARCHIVE_ID/cfg/static/style/auto/zzz_local.css</code>.</p> | ||
| + | <p>You can create additional CSS files if you need.</p> | ||
| + | <p><i>Note: Files are loaded in alphabetical order, hence the zzz_ prefix.</i></p> | ||
| + | |||
| + | ==== Javascript ==== | ||
| + | <p>Your custom Javascript should go in <code>/opt/eprints3/archives/ARCHIVE_ID/cfg/static/javascript/auto/90_local.js</code>.</p> | ||
| + | <p>You can create additional .js files if you need.</p> | ||
| + | <p><i>Note: Files are loaded in alphabetical order, hence the 90_ prefix.</i></p> | ||
| + | |||
| + | ==== Media ==== | ||
| + | <p>Images for your site should go in <code>/opt/eprints3/archives/ARCHIVE_ID/cfg/static/images/</code>.<p> | ||
| + | <p>You can then load your images from <code><nowiki>http://ARCHIVE_ID.your_domain_here.net/images/EXAMPLE_IMAGE.jpg</nowiki></code> eg: <code><nowiki>https://demo.eprints-hosting.org/images/eprintslogo.png</nowiki></code> | ||
| + | |||
| + | == Find Out More == | ||
| + | You can find out more in our templating guide, [[Branding_with_confidence | Branding with Confidence]] | ||
| + | |||
| + | = Functionality = | ||
| + | |||
| + | == Core Files == | ||
| + | <p>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.</p> | ||
=== Views === | === Views === | ||
| + | <p>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.</p> | ||
| + | <p>The configuration for browse views can be found in <code>views.pl</code>, which by default is found under <code>/opt/eprints3/flavours/pub_lib/cfg.d/</code> but should be copied to the archive's <code>cfg/cfg.d/</code> for editing.</p> | ||
| + | |||
| + | <p>See the [[:Category:Browse_Views | Browse Views Category]] for more information.</p> | ||
=== Workflows === | === Workflows === | ||
| + | <p>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.</p> | ||
| + | <p>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 <code>default.xml</code> in <code>/opt/eprints3/flavours/pub_lib/workflows/eprint/</code>. If this needs to be modified it should be copied to the archive's <code>/opt/eprints3/ARCHIVE_ID/cfg/workflows/eprint/</code> directory before editing.</p> | ||
| + | |||
| + | <p>Explanation of the various elements and attributes are described in the [[Workflow_Format | Workflow Format Guide]].</p> | ||
| + | |||
| + | === Searches === | ||
| + | ==== Simple ==== | ||
| + | Simple search by default provides a single text field for users to enter their search terms to search across a selection of different attributes of a publication. Typically this simple search will be included on repository's home page or as part of the template so users can conduct a search from any page. The simple search form can be found at: | ||
| + | http://EPRINTS_HOSTNAME/cgi/search/simple | ||
| + | If you want to generate a pre-canned search the search terms are sent under the "q" parameter, e.g. | ||
| + | https://demo.eprints-hosting.org/cgi/search/simple?q=Science | ||
| + | |||
| + | <p>The attributes it searches on can be modified by copying <code>eprint_search_simple.pl</code> from <code>/opt/eprints3/lib/defaultcfg_zero/cfg.d/</code> to <code>/opt/eprints3/archives/ARCHIVE_ID/cfg/cfg.d/</code> and modifying the meta_fields section.</p> | ||
| + | <p>Other search options such as search results ordering, paging and formatting can also be modified.</p> | ||
| + | |||
| + | ==== Advanced ==== | ||
| + | <p>Advanced Search allows a user to filter a search to specific terms and items, this search typically exists on its own page to give space for different filtering options.</p> | ||
| + | <p>The advanced search page can be found at:</p> | ||
| + | http://EPRINTS_HOSTNAME/cgi/search/advanced | ||
| + | eg: | ||
| + | https://demo.eprints-hosting.org/cgi/search/advanced | ||
| − | + | <code>eprint_search_advanced.pl</code> contains configuration for the advanced search on eprint data objects, it can be copied from <code>/opt/eprints3/lib/defaultcfg_zero/cfg.d/</code> to <code>/opt/eprints3/archives/ARCHIVE_ID/cfg/cfg.d/</code> and modified. | |
| − | === | + | ==== Find Out More ==== |
| + | <p>For more details on editing search, see our [[Search.pl | Search Guides]].</p> | ||
| + | == Extending == | ||
| + | <p>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 === | === Ingredients === | ||
| + | <p>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.</p> | ||
| + | <p>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 <code>/opt/eprints3/ingredients/</code>.</p> | ||
| + | <p>With the files ready, the ingredient then needs to be installed into the system, see our [[Installing Ingredients | Installing Ingredients Guide]] for more details</p> | ||
=== EPMs/Bazaar Plugins === | === EPMs/Bazaar Plugins === | ||
| + | <p>Now mostly superceeded by Ingredients, in previous versions of EPrints the Bazaar was the preferred method of extending the functionality of an EPrints system. You may find some functionality still requires you install an EPM package from the Bazaar.</p> | ||
| + | <p>You can find more information on installing an EPM on our [[Installing an EPM |Installing an EPM]] page. | ||
Latest revision as of 11:58, 9 October 2026
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.
Re-Generate Pages
After updating your global template you will need to run
/opt/eprints3/bin/generate_static ARCHIVE_ID /opt/eprints3/bin/generate_views ARCHIVE_ID /opt/eprints3/bin/generate_abstracts ARCHIVE_ID
to regenerate the pages across the site.
Static Pages
Static pages use the global templates (see [#Site_Templates |above]) as a wrapper for the content they contain. The content can be modified by editing the relevant file, the most prominant static page is the homepage, the template file for it is index.xpage and can be found at /opt/eprints3/lib/themes/example/lang/en/static/index.xpage. It should be copied to /opt/eprints3/archives/ARCHIVE_ID/cfg/lang/en/static/ before being modified. Additional templates can be created in the same archive level /static directory for other pages.
Re-Generate Pages
After updating your template you will need to run /opt/eprints3/bin/generate_static ARCHIVE_ID to regenerate the pages
Find out More
Find out more about static pages here.
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.
Searches
Simple
Simple search by default provides a single text field for users to enter their search terms to search across a selection of different attributes of a publication. Typically this simple search will be included on repository's home page or as part of the template so users can conduct a search from any page. The simple search form can be found at:
http://EPRINTS_HOSTNAME/cgi/search/simple
If you want to generate a pre-canned search the search terms are sent under the "q" parameter, e.g.
https://demo.eprints-hosting.org/cgi/search/simple?q=Science
The attributes it searches on can be modified by copying eprint_search_simple.pl from /opt/eprints3/lib/defaultcfg_zero/cfg.d/ to /opt/eprints3/archives/ARCHIVE_ID/cfg/cfg.d/ and modifying the meta_fields section.
Other search options such as search results ordering, paging and formatting can also be modified.
Advanced
Advanced Search allows a user to filter a search to specific terms and items, this search typically exists on its own page to give space for different filtering options.
The advanced search page can be found at:
http://EPRINTS_HOSTNAME/cgi/search/advanced
eg:
https://demo.eprints-hosting.org/cgi/search/advanced
eprint_search_advanced.pl contains configuration for the advanced search on eprint data objects, it can be copied from /opt/eprints3/lib/defaultcfg_zero/cfg.d/ to /opt/eprints3/archives/ARCHIVE_ID/cfg/cfg.d/ and modified.
Find Out More
For more details on editing search, see our Search Guides.
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/.
With the files ready, the ingredient then needs to be installed into the system, see our Installing Ingredients Guide for more details
EPMs/Bazaar Plugins
Now mostly superceeded by Ingredients, in previous versions of EPrints the Bazaar was the preferred method of extending the functionality of an EPrints system. You may find some functionality still requires you install an EPM package from the Bazaar.
You can find more information on installing an EPM on our Installing an EPM page.
