EPrints Documentation - User contributions [en-gb]

Dynamic templates

2007-04-11T21:47:12Z

Fmccown: Redirect

#REDIRECT [[Dynamic Template System]]

Change Deposit Status in Bulk

2007-04-10T18:44:01Z

Fmccown:

At times it may be useful for you to move a large number of deposits from "User Workarea" to "Live Archive". While you could do this manually using the Web interface one-by-one, this could be a very time-consuming process.

To change a large number of deposits, execute the following update command in MySQL:

<code>
UPDATE eprint SET eprint_status="archive" WHERE userid=3 AND eprint_status="inbox"
</code>

or

<code>
UPDATE eprint SET eprint_status="archive" WHERE eprintid < 101
</code>

depending on the criteria that identifies the deposits you want to change.

Then you will need to run <tt>generate_abstracts</tt> in order for the deposited items to have an abstract page:

<code>
/opt/eprints3/bin/generate_abstracts <archive_id>
</code>

Now your items should be availabe from the repository.

Branding, the next level

2007-03-23T19:53:24Z

Fmccown: General clean-up

This document describes how to completely customise the template of your EPrints 3 repository. Not just changing some colour schemes and images, but a reworking of the structure of the HTML.

== Introduction ==
The redesign process is not an easy one.<br/>
No, let me rephrase that: When designing a complete re-branding, altering the EPrints files is pretty - easy however the design, the xhtml and the css all requires some skill and knowledge. That part of the process is not discussed here, sorry.

== Step One: design ==
Get the design right.<br/>
Speak to Web Designers/Greaphic Artists about layout/graphics/composition.<br/>
Speak to xhtml coders and CSS monkeys about accessibility, cross-browser compatibility, and good practice.<br/>
Make up some static pages to get the page right ''before'' you edit any EPrints files.

This is the design I'm going to talk about:
[[Image:overview.png]]

== Step Two: implement ==
Let us assume that you have configured the basic repository, created the database, and created an admin user.<br/>
Let us further assume that you are at the top of the installed EPrints software (<code>/opt/</code> or <code>/usr/local</code> or <code>/home/eprints</code> or wherever you've installed it)

Edit the default template for your repository:
<pre>
vi archives/ARCHIVEID/cfg/lang/en/templates/default.xml
</pre>

Edit the file, or delete all the contents and start again.
=== Head section ===
<pre>

<?xml version="1.0" standalone="no" ?>
<!DOCTYPE html SYSTEM "entities.dtd" >

<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epc="http://eprints.org/ep3/control" xml:lang="en" lang="en">
<head>
<title><epc:pin ref="title" textonly="yes"/> - <epc:phrase ref="archive_name"/></title>
<script src="/javascript/auto.js" type="text/javascript"></script>
<style type="text/css" media="screen">@import url(/style/auto.css);</style>
<style type="text/css" media="screen"> @import url(/style/eprints.css); </style>
<style type="text/css" media="print">@import url(/style/print.css);</style>


<link rel="icon" href="/favicon.ico" type="image/x-icon"/>
<link rel="shortcut icon" href="/favicon.ico" type="image/x-icon"/>
<link rel="Top" href="{$config{frontpage}}"/>
<link rel="Search" href="/perl/search"/>
<epc:pin ref="head"/>
</head>

</pre>

This is the head section of the xhtml for our demo page. <br/>
* <code><title><epc:pin ref="title" textonly="yes"/> - <epc:phrase ref="archive_name"/></title></code> shows that the title is made from two elements defined in one of the ''phrases'' files
* <code><script src="/javascript/auto.js" type="text/javascript"></script></code> is the line that pulls in the auto-completer javascript
* <code><style type="text/css" media="screen">@import url(/style/auto.css);</style></code> is the bit that pulls in all the default javascript styling
* <code><style type="text/css" media="screen"> @import url(/style/eprints.css); </style></code> is my extra CSS for my design
* <code><style type="text/css" media="print">@import url(/style/print.css);</style></code> is the css that is referenced when printing to the page
* <code></code> is my hack to include IE-specific CSS that the web validators won't see (or complain about)
* <code><epc:pin ref="head"/></code> is a pin-holder for any extra head-section tags that are defined (''where?'')

=== Body section ===
<pre>

<body>
<div class="ep_noprint"><noscript><style type='text/css'>@import url(/style/nojs.css);</style></noscript></div>
<div id="container">
<div id="banner" class="ep_noprint">
<div id="banner_inner">
<span id="the_depot_logo" >The DEPOT</span>
</div> 
</div> 
<div id="main_area" class="clearfix"> 
<div id="top_menu" class="ep_noprint" >
<div id="tabcontainer">

<ul id="navtabs"><epc:pin ref="login_status"/></ul>
</div> 
</div> 
<div id="content" >
<epc:pin ref="page"/>
</div> 
</div> 
<div id="footer" class="clearfix ep_noprint">
<img src="/images/logos.gif" title="Logos for EDINA and SHERPA" alt="[LOGOS]" class="edina_logo" style="float:left"/>
<span id="banner_image_copyright">Banner image © JupiterImages 2006</span>
<div id="credit">This service is running on <em>GNU EPrints</em> repository-creating software, which generates
repositories that are compliant with the <a href="http://www.openarchives.org">Open Archives Protocol for
Metadata Harvesting OAI 2.0</a>.<br />
<span id="take_down">» <a href="/policy.html" title="What to do when you discover a deposit that infringes
UK laws">how to complain</a> about a paper in the Depot</span></div>
</div> 
</div>
</body>

</pre>

So - what do we have here?
* <code><noscript><style type='text/css'>@import url(/style/nojs.css);</style></noscript></code> is a non-complient ''bodge'' to include extra CSS (used by the core eprints code) when there is no Javascript available.
* <code><ul id="navtabs"><epc:pin ref="login_status"/></ul></code> is the bit that defines the toolbar (more later)
* <code><epc:pin ref="page"/></code> is the bit that defines where the code sits
The rest is all design and layout (and there is a ''lot'' of design and layout in <code>/style/eprints.css</code>

== Toolbar ==

=== Changing the separator ===
The toolbar in a standard EPrints system is a series of <span>'ed items, with a defined separator.

To change the seperator to (say) the hash symbol ('#'), edit the file <code>archives/deposit/cfg/lang/en/phrases/dynamic.xml</code> and add
<pre>
<epp:phrase id="Plugin/Screen:tool_divide"> # </epp:phrase>
</pre>
(the <code>dynamic.xml</code> file needs to be valid XML, so you can't change the separator to something like <code></li><li></code>.)

=== Changing the toolbar items ===
The toolbar is dynamically created.
* there is one form for an anonymous user
** (this is where a user logs in, or creates a new account)
*** [[image:anon_toolbar.png]]
* and one for a logged in user
** The toolbar for an admin-level user could look like:
*** [[image:admin_toolbar.png]]

To deviate from the default toolbar, you will need to provide your own xhtml. Edit <code>archives/deposit/cfg/lang/en/phrases/dynamic.xml</code> and add:
<pre>
<epp:phrase id="dynamic:not_logged_in"><li><a class="h_menulink" href="/view/">Browse</a></li><li><a class="h_menulink" href="{$config{userhome}}">Login</a></li><li><a class="h_menulink" href="{$config{perl_url}}/register">Create Account</a></li></epp:phrase>

<epp:phrase id="dynamic:logged_in"><li class="logged_in_as" style="float: right">Logged in as <epc:pin name="user"/></li><li><a class="h_menulink" href="/view/">Browse</a></li><epc:pin name="tools" /><li><a class="h_menulink" href="{$config{perl_url}}/logout">Logout</a></li></epp:phrase>
</pre>
my example is different from the standard EPrints layout in that I am also switching to using a list for each of my toolbar items

'''Note''': the use of the xhtml comments as above is part of a CSS "trick"

=== Removing items from the user list ===
Items can easily be removed from the toolbar (I have removed the '''Saved Searches''' item.)

Edit <code>archives/deposit/cfg/cfg.d/plugins.pl</code>
<pre>
# option to disable the functionality all together
$c->{plugins}->{"Screen::User::SavedSearches"}->{params}->{disable} = 1;

# option to keep the functionality, but leave it out the toolbar
$c->{plugins}->{"Screen::Items::SavedSearches"}->{appears}->{key_tools} = undef;
</pre>

=== Changing the actual format ===

In my example, we have actually changed the toolbar to be a series if List Items (<code><li>foo</li></code>)

This is somewhat more complex, and requires code-hacking

The toolbar is created in <code>perl_lib/EPrints/Session.pm</code>, in a function called <code>render_toolbar</code>.

This needs to be changed in several places, however in essence, to need to replace:
<pre>
my $first = 1;
foreach my $tool ( @core )
{
if( $first )
{
$first = 0;
}
else
{
$core->appendChild( $self->html_phrase( "Plugin/Screen:tool_divide" ) );
}
my $a = $self->render_link( $url."?screen=".substr($tool->{screen_id},8) );
$a->appendChild( $tool->{screen}->render_title );
$core->appendChild( $a );
}
</pre>
with:
<pre>
foreach my $tool ( @core )
{
my $a = $self->render_link( $url."?screen=".substr($tool->{screen_id},8) );
$a->appendChild( $tool->{screen}->render_title );
my $li = $self->make_element('li', class=>"");
$li->appendChild($a);
$core->appendChild( $li );
}
</pre>
(Thanks to Ben Wheeler for that)

== Rebuild the web pages ==
Every time you alter <code>archives/ARCHIVEID/cfg/lang/en/templates/default.xml</code>, you need to regenerate the pages of the service:
<pre>
bin/generate_static ''archiveID''
bin/generate_views ''archiveID''
bin/generate_abstracts ''archiveID''
</pre>

Every time you alter any of the <code>.xml</code> you need to reload the configuration:
<pre>
bin/epadmin reload ''archiveID''
</pre>
(though a proper web server restart is the best thing to do once you are happy with the configuration:
<pre>
/path/to/web_server/bin/apachecfg restart
</pre>

Branding with confidence

2007-03-23T19:48:53Z

Fmccown: Added See also

{{development}}

One of the most common EPrints customisations is to add your own institution's branding and "look and feel" to the interface - this may include logos, page layouts, stylesheets and colour schemes.

__TOC__

==Branding fast track==

This section describes techniques for very quickly changing the appearance of your EPrints repository. These techniques could be useful, for example, to quickly brand a demonstration repository so that your audience can identify with it.

===Adding a logo===

'''Example 1

The simplest approach is to overwrite the default EPrints logo with a copy of your own logo. Copy your logo to:

/opt/eprints3/archives/ARCHIVEID/cfg/static/images/sitelogo.gif

Place the new image on the web site by typing:


bin/generate_static ARCHIVEID

Your logo should now be displayed in place of the default EPrints logo.

'''Example 2

The image that EPrints uses for the site logo is defined in the branding configuration file. You can change this setting to point to the logo image on your institution's Web page.

Open the branding configuration file in a text editor:

/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/branding.pl

Find the site_logo configuration setting:

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

Change the setting to point to your own logo image:

<pre>
$c->{site_logo} = "<nowiki>http://www.soton.ac.uk/img/furniture/royal/corp_logo.gif</nowiki>";
</pre>

Reload the EPrints configuration by typing:

bin/epadmin reload ARCHIVEID

'''Example 3

You can also adjust the site_logo configuration setting to point any local image file. Place a copy of your logo image somewhere in the /opt/eprints3/archives/ARCHIVEID/cfg/static/images/ directory and then update the branding configuration file to point to it.

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

Reload the EPrints configuration by typing:

bin/epadmin reload ARCHIVEID

and then place the new logo file into the website:

bin/generate_static ARCHIVEID

===Changing the theme===

Open the branding configuration file in a text editor:

/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/branding.pl

Find the theme configuration setting:

# $c->{theme} = "green";

Change the setting to use the chosen theme.

$c->{theme} = "green";

''Currently EPrints 3 only includes the default and "green" theme, but look out for more themes in future versions of EPrints and on the http://files.eprints.org/ community repository.

==Taking control==

This section describes techniques for taking complete control of the appearance of your repository.

===Changing the page layout===

Every page in your repository is displayed using a single template. A custom layout can be applied to your repository pages by editing this template directly.

Open the template file for your repository:

/opt/eprints3/archives/ARCHIVEID/cfg/lang/en/templates/default.xml

The template is an XHTML file with some additional syntax (see [[Template Format]]).

====Pins====

You will notice a number of epc:pin elements. These tell EPrints how to combine the template with page-specific content to build each individual page.

'''Example

<pre>
<div align="center">
<epc:pin ref="toolbar" />
<table width="720" class="ep_tm_main"><tr><td align="left">
<h1 class="ep_tm_pagetitle"><epc:pin ref="title"/></h1>
<epc:pin ref="page"/>
</td></tr></table>
</div>
</pre>

This part of the template lays out the main content area of the page (the ''page'' pin) inside a fixed width table, which is centered on the page. The toolbar (''toolbar'' pin) and title of the page (''title'' pin) are laid out above the main content.

You can incorporate the epc:pin elements however you like into your new layout (although note that the head pin should always be inside the head section of the template, and the pagetop pin should be at the start of the body section). You can also define new pins (see below).

====Configuration Strings====

There are also a number of epc:print elements in the default template which are useful for including configuration values in the template.

'''Example

<style type="text/css" media="screen">@import url(<epc:print expr="$config{base_url}"/>/style/auto.css);</style>

This extract from the head section of the template shows how an epc:print element is used to refer to the base URL of the repository. This avoids hardcoding URLs into the template (which is good for maintainability - if the repository URL should change, you do not have to change the template).

Configuration values can also be used inside attributes, using the {...} syntax.

'''Example

<a href="{$config{frontpage}}"><img alt="Logo" src="{$config{site_logo}}" /></a>

This extract shows how the URL of both the front page of the repository and the logo are derived from the configuration rather than being hard coded directly into the template.

====Template checklist====

A typical repository page layout will include:

# the correct XML declaration at the top of the file
# a head section (load default and custom stylesheets, ''title'' and ''head'' pins)
# a body section, containing:
## ''pagetop'' pin
## header (repository title and logo)
## navigation menu (links to browse, search etc.)
## quick search box
## toolbar (''login_status'' and ''toolbar'' pins)
## main content area (''title'' and ''page'' pins)
## footer (copyright notice etc.)

====Loading the new template====

Load your new template by running:

bin/epadmin reload ARCHIVEID

====Dealing with template errors====

A common cause of errors when loading a new template is that the template is not ''well formed''. The template is in XHTML syntax, and therefore must follow the rules for writing well-formed XML documents:

* http://en.wikipedia.org/wiki/XML#Well-formed_documents

'''Example

You get the following error when reloading the template:

parser error : Opening and ending tag mismatch: img line 25 and div

Open the template file, and look for an img tag on line 25:

<img src="/images/mylogo.gif">

The problem is that the img tag is opened, but there is no closing img tag. The img element is empty, so we can add a self-closing tag to make the eleemtn well formed:

<img src="/images/mylogo.gif" />

'''Example

parser error : Opening and ending tag mismatch: p line 60 and body

Open the template file and look for the p tag on line 60:

<pre>
<p>This repository is maintained by the <b>Library and Computing team</b>.
</pre>

There is no closing p tag. The p element is not empty, so we add a closing p tag at the end of the paragraph to make the element well formed:

<pre>
<p>This repository is maintained by the <b>Library and Computing team</b>.</p>
</pre>

===Adding extra images===

If your new layout requires additional images, or if you want to add additional images to the default layout, you need to place a copy of each image in your repository's image directory:

/opt/eprints3/archives/ARCHIVEID/cfg/static/images/

Process the images by running:

bin/generate_static ARCHIVEID

The image can then be used in the template.

'''Example

Place a copy of small_logo.gif in:

/opt/eprints3/archives/ARCHIVEID/cfg/static/images/

Use the image in the template:

<img src="/images/small_logo.gif" />

===Working with stylesheets===

EPrints has [[EPrints_Directory_Structure/eprints3/lib/static/style/auto|several stylesheet files]], each of which contains style rules for a specific aspect of the repository. By default these stylesheets are applied to every repository page, in alphabetical order.

The default stylesheets can be found here:

/opt/eprints3/lib/static/style/auto/

====Overriding default style rules====

You may decide that you want to override a particular rule in one of the default stylesheets. Rather than edit the default stylesheet directly (since the edited rule will then be applied to any other repositories running on the same server), you should override the rule in your repository's overrides file:

/opt/eprints3/archives/ARCHIVEID/cfg/static/style/auto/zzz_local.css

Remember that the stylesheets are applied in alphabetical order, so this file will be applied last.

'''Example

h1 {
margin: 0px 0px 10px 0px;
font: bold 130% Arial,Sans-serif;
text-align: center;
color: #606060;
}

This rule is from general.css and defines how the h1 (heading level 1) element should be displayed (in the default template, h1 is used to display the title of the page).

Edit the local overrides file for your repository:

/opt/eprints3/archives/ARCHIVEID/cfg/static/style/auto/zzz_local.css

Override the ''font'' part of the h1 style:

h1 {
font: bold 200% Arial,Sans-serif;
}

Apply the new style rules by running:

bin/generate_static ARCHIVEID

This renders the page title on each page in a larger font.

====Overriding default stylesheets====

If you want to override a default stylesheet in its entirety, you should copy it into your repository's stylesheet directory and edit it there.

'''Example

Make a copy of the default stylesheet general.css:

cp /opt/eprints3/lib/static/style/auto/general.css /opt/eprints3/archives/ARCHIVEID/cfg/static/style/auto/

Edit the repository copy:

/opt/eprints3/archives/ARCHIVEID/cfg/static/style/auto/general.css

After making changes to the repository copy of general.css, apply the new stylesheet by running:

bin/generate_static ARCHIVEID

====Adding institutional stylesheets====

Your institutional Web site may already have a stylesheet or set of stylesheets that you want to apply to your repository.

Copy the institutional stylesheets into your repository stylesheet directory:

/opt/eprints3/archives/ARCHIVEID/cfg/static/style/

Process the stylesheets by running:

bin/generate_static ARCHIVEID

The stylesheets are then available to use in the template file.

'''Example

<head>
...
<style type="text/css" media="screen">@import url(<epc:print expr="$config{base_url}"/>/style/auto.css);</style>
<style type="text/css" media="screen">@import url(<epc:print expr="$config{base_url}"/>/style/my_inst.css);</style>

Here we add a stylesheet link to our institutional stylesheet my_inst.css to the head section of the template. Note that we apply my_inst.css ''after'' the repository stylesheets (applied in order by auto.css) so that the institutional style rules override the repository style rules.

====Adding extra style-related images====

If your new stylesheet requires additional images (eg. background images for tables or divs), you need to place a copy of each image in your repository style/image directory:

/opt/eprints3/archives/ARCHIVEID/cfg/static/style/images/

Note that this keeps the style-related images separate from other images used by your repository pages, such as logos.

Process the images by running:

bin/generate_static ARCHIVEID

The images can then be used in your stylesheet.

===Adding dynamic content===

You can add dynamic content to the template by adding extra epc:pin elements. EPrints uses this technique to display the current user's login status on the menu bar. Open the repository template file:

/opt/eprints3/archives/ARCHIVEID/lang/en/templates/default.xml

Locate the login_status pin:

<pre>
<table class="ep_tm_searchbar" border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left"><epc:pin ref="login_status"/></td>
</pre>

The content of the login_status pin, and other dynamic pins, is created in the dynamic template configuration file:

/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/dynamic_template.pl

'''Example

Open the template file for your repository:

/opt/eprints3/archives/ARCHIVEID/cfg/lang/en/templates/default.xml

Add a new pin called ''todays_date'' to the template; here we add the pin next to the user's login status:

<pre>
<td align="left"><epc:pin ref="todays_date"/></td>
<td align="left"><epc:pin ref="login_status"/></td>
</pre>

Open the dynamic template configuration file for your repository:

/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/dynamic_template.pl

Ensure that the dynamic template feature is enabled (this is the default):

$c->{dynamic_template}->{enable} = 1;

Find the function that creates the content for the dynamic pins:

$c->{dynamic_template}->{function} = sub {
...
};

Note the code which generates the content for the ''login_status'' pin and add a line underneath which creates the content for the ''todays_date'' pin:

$parts->{todays_date} = $session->make_text( scalar localtime );

Reload the dynamic template configuration:

bin/epadmin ARCHIVEID

The date should now be displayed on your repository pages.

== See also ==
* [[Branding, the next level]]

Cgi/

2007-03-23T16:29:09Z

Fmccown: google_site description

{{dirs}}

These scripts handle the dynamic parts of the website.

*'''[[EPrints_Directory_Structure/eprints3|eprints3]]/cgi'''
** '''confirm''' -
** '''counter''' - Provides some simple machine-readable stats on the repository.
** '''export''' -
** '''google_site''' - Searches the repository host with given search terms using Google.
** '''handle_404''' -
** '''latest''' -
** '''latest_tool''' -
** '''latex2png''' -
** '''logout''' -
** '''oai2''' - The OAI interface.
** '''oai_accesslogs''' -
** '''openurl''' -
** '''paracite''' -
** '''register''' -
** '''request_doc''' -
** '''reset_password''' -
** '''saved_search''' -
** '''search''' -
** '''[[EPrints_Directory_Structure/eprints3/cgi/users|users/]]''' - This directory contains scripts which require a valid login.

Manual

2007-03-23T15:45:22Z

Fmccown: /* How-to Guides */ Statuses -> Status

See the [[Main Page]] for other areas of this wiki.
__NOTOC__
= Introduction =

* [[Introduction]]
* How to Get Help/Support
* [[History]]

= Installing EPrints & Getting Started =

* [[Required software]]
* [[Installation|Installing EPrints]]
** [[Recommended Platforms]]
** [[Installing Eprints 3 on Fedora Core 6]]
** [[Installing EPrints 3 on RedHat Enterprise 4]]
** [[Installing EPrints 3 on OS X]]
** ''[[:Category:Installation|other platforms]]''
* Upgrading EPrints 3 versions
* [[Migration|Migrating from EPrints 2.3]]
* [[Getting Started with EPrints 3|Getting Started]]
* [[Backups]]
* [[Troubleshooting]]
* Advanced Installation
** [[HTTPS]]
* [[:Category:Installation|Installing]] EPrints on various platforms.

= How-to Guides =

''[http://en.wikipedia.org/wiki/Howto What is a how-to?]

* Orientation <span style="color: #f94; font-size: 130%">(Start here)</span>
** [[Configuration orientation|New to EPrints 3?]] - ''before diving into the how-tos, take some time to read through this brief orientation guide and familiarise yourself with the EPrints configuration landscape...''
** [[EPrints_3_Configuration_orientation_for_EPrints_2_administrators|Migrated from EPrints 2?]] - ''this orientation guide is intended to help you re-orient yourselves in your new EPrints 3 set up...''
* [[Branding with confidence]] - ''one of the most common EPrints customisations is to add your own institution's branding and "look and feel" to the interface...''
** [[Branding, the next level]] - ''how to completely change the interface to your own design''
* [[Adding new views]]
* Workflow
* Deposit Types
* Metadata
* Subjects (fold in with Organisation Hierarchy under "controled vocabularies")
* [[EPrints_3_Organisation_Hierarchy|Organisation Hierarchy]] - ''how to put your own organisation's Hierarchy into EPrints 3''
* Searches
* [[Autocompletion and Authority Files (Romeo Autocomplete)]] - ''add autocomplete functionality to the Publication Title input field based on an authority file downloaded from EPrints Romeo...''
* [[Create Export Plugins]] - ''create a Perl Module that will export your data...''
* [[Login-Only Repository]] - ''require a username and password to access all pages (including search, browse, and the front page)...''
* [[Change Deposit Status in Bulk]] - ''move a large number of deposits from inbox to archive
* [[Customisation|more]]

= Misc =

* [[Preservation Support]] in GNU EPrints 3
* I18n
* [[How to contribute]]
** [[Extension Packages]]

= Technical Reference =

* [[EPrints Directory Structure]] - will be linked somewhere better, later.

* [[Metadata]] - configuring metadata fields.
* [[Archives/ARCHIVEID/cfg/|Repository Configuration]]
* [[XML Configuration]] Files
** [[EPScript]] - documentation for the EP3 Scripting language (for use in citations and workflow files).
** [[EPrints Control Format]] - the structure used to embed EPScript in an XML configuration file.
** [[Citation Format]]
** [[Workflow Format]] - the structure of the EP3 workflow files
** [[Phrase Format]]
** [[Template Format]]
** [[XPAGE Format]]
* [[XML Export Format]]
* EPrints data structure
** of the software
** of the database (relating the dataobjects to each other using eprints fields)
* [[Data Object]]s and data sets
** The [[EPrint Object]]
** The [[User Object]]
** The [[Document Object]]
** The [[Subject Object]]
** The [[Saved Search Object]]
** The [[History Object]]
** The [[Access Object]]
** The [[Request Object]]
* Plugins
** Import
** [[Export Plugins]]
** Components
** Screen
** Convert
* [[Autocompletion]]
** [[Understanding IDs in Workflow Forms]]
* [[API]]

Change Deposit Status in Bulk

2007-03-23T15:42:24Z

Fmccown: Change Deposit Statuses in Bulk moved to Change Deposit Status in Bulk

At times it may be useful for you to move a large number of deposits from "User Workarea" to "Live Archive". While you could do this manually one-by-one, this could be a very time-consuming process.

To change a large number of deposits, execute the following update command in MySql:

<code>
UPDATE eprint SET eprint_status="archive" WHERE userid=3 AND eprint_status="inbox"
</code>

or

<code>
UPDATE eprint SET eprint_status="archive" WHERE eprintid < 101
</code>

depending on the criteria that identifies the deposits you want to change.

Then you will need to run <tt>generate_abstracts</tt> in order for the deposited items to have an abstract page:

<code>
/opt/eprints3/bin/generate_abstracts <archive_id>
</code>

Now your items should be availabe from the repository.

Change Deposit Statuses in Bulk

2007-03-23T15:42:24Z

Fmccown: Change Deposit Statuses in Bulk moved to Change Deposit Status in Bulk: Better sounding title

#redirect [[Change Deposit Status in Bulk]]

Manual

2007-03-21T20:15:06Z

Fmccown: /* How-to Guides */ Link to Change Deposit Statuses in Bulk

See the [[Main Page]] for other areas of this wiki.
__NOTOC__
= Introduction =

* [[Introduction]]
* How to Get Help/Support
* [[History]]

= Installing EPrints & Getting Started =

* Installing Required Software
* [[Installation|Installing EPrints]]
** [[Recommended Platforms]]
** [[Installing Eprints 3 on Fedora Core 6]]
** [[Installing EPrints 3 on RedHat Enterprise 4]]
** [[Installing EPrints 3 on OS X]]
** ''[[:Category:Installation|other platforms]]''
* Upgrading EPrints 3 versions
* [[Migration|Migrating from EPrints 2.3]]
* [[Getting Started with EPrints 3|Getting Started]]
* [[Backups]]
* Troubleshooting
* Advanced Installation
** [[HTTPS]]
* [[:Category:Installation|Installing]] EPrints on various platforms.

= How-to Guides =

''[http://en.wikipedia.org/wiki/Howto What is a how-to?]

* Orientation <span style="color: #f94; font-size: 130%">(Start here)</span>
** [[Configuration orientation|New to EPrints 3?]] - ''before diving into the how-tos, take some time to read through this brief orientation guide and familiarise yourself with the EPrints configuration landscape...''
** [[EPrints_3_Configuration_orientation_for_EPrints_2_administrators|Migrated from EPrints 2?]] - ''this orientation guide is intended to help you re-orient yourselves in your new EPrints 3 set up...''
* [[Branding with confidence]] - ''one of the most common EPrints customisations is to add your own institution's branding and "look and feel" to the interface...''
** [[Branding, the next level]] - ''how to completely change the interface to your own design''
* [[Adding new views]]
* Deposit Types and Metadata
* [[EPrints_3_Organisation_Hierarchy|Organisation Hierarchy]]
* Searches
* [[Autocompletion and Authority Files (Romeo Autocomplete)]] - ''add autocomplete functionality to the Publication Title input field based on an authority file downloaded from EPrints Romeo...''
* [[Create Export Plugins]] - ''create a Perl Module that will export your data...''
* [[Login-Only Repository]] - ''require a username and password to access all pages (including search, browse, and the front page)...''
* [[Change Deposit Statuses in Bulk]] - ''move a large number of deposits from inbox to archive
* [[Customisation|more]]

= Misc =

* [[Preservation Support]] in GNU EPrints 3
* I18n
* [[How to contribute]]
** [[Extension Packages]]

= Technical Reference =

* [[EPrints Directory Structure]] - will be linked somewhere better, later.

* [[Metadata]] - configuring metadata fields.
* [[Archives/ARCHIVEID/cfg/|Repository Configuration]]
* [[XML Configuration]] Files
** [[EPScript]] - documentation for the EP3 Scripting language (for use in citations and workflow files).
** [[EPrints Control Format]] - the structure used to embed EPScript in an XML configuration file.
** [[Citation Format]]
** [[Workflow Format]] - the structure of the EP3 workflow files
** [[Phrase Format]]
** [[Template Format]]
** [[XPAGE Format]]
* [[XML Export Format]]
* EPrints data structure
** of the software
** of the database (relating the dataobjects to each other using eprints fields)
* [[Data Object]]s and data sets
** The [[EPrint Object]]
** The [[User Object]]
** The [[Document Object]]
** The [[Subject Object]]
** The [[Saved Search Object]]
** The [[History Object]]
** The [[Access Object]]
** The [[Request Object]]
* Plugins
** Import
** [[Export Plugins]]
** Components
** Screen
** Convert
* [[Autocompletion]]
** [[Understanding IDs in Workflow Forms]]
* [[API]]

Change Deposit Status in Bulk

2007-03-21T20:13:27Z

Fmccown: Initial article

Bin/

2007-03-21T14:22:59Z

Fmccown: Link to generate_views

{{dirs}}

Command-line tools. These are used either directly from the command line, or set to be run every so often, using cron.

Use the --man option on the command line to get more information about these tools.

eg.
# /opt/eprints3/bin/export --man

*[[EPrints_Directory_Structure/eprints3|eprints3]]/bin/
** '''epadmin''' - Perform admin tasks including creating repositories.
** '''epindexer''' - UNIX script to start the EPrints indexer when the server reboots. Do not call directly.
** '''explain_sql_tables''' - Gives a brief summary of the purpose of each SQL table.
** '''[[EPrints Directory Structure/eprints3/bin/export|export]]''' - Export data from the system using an export plugin.
** '''generate_abstracts''' - Update all the Metadata-Summary pages. (The page for a single EPrint which links to the documents)
** '''generate_apacheconf''' - Update the apache configuration files.
** '''generate_static''' - Update all the static web pages.
** '''[[generate_views]]''' - Update all the /view/ pages.
** '''import''' - Import data from a file using an import plugin.
** '''import_subjects''' - Import the subject tree from a text file or XML file.
** '''indexer''' - This is a daemon which runs in background and indexes the words in documents, titles, abstracts etc. so that they can be searched.
** '''lift_embargos''' - This script should be run once a day. It removes security on documents which embargo date has passed.
** '''list_user_emails''' - This just outputs all the users emails as a text file. Handy for making a mailing list.
** '''make_latest''' - Makes a file for the specified archive with latest items. (still a bit experimental in 3.0)
** '''send_alerts''' - This should also be run daily, weekly and monthly with the appropriate options. Sends out saved search emails.
** '''startup.pl''' - Used by apache to load modules for mod_perl. Does not do anything useful on the command line.

Getting Started with EPrints 3

2007-03-21T14:21:54Z

Fmccown: /* Browse Views */ Link to generate_views

==Creating an Archive==

EPrints 3 can run run multiple archives under one install. Multiple archives will require giving additional DNS aliases to the machine running EPrints, EPrints can then create all the parts of the apache configuration file needed to run the virtual hosts.

===Running epadmin===
Make sure MySQL is actually running.

Change to your eprints user (probably "eprints").

Change directory to the eprints directory (<tt>/opt/eprints3</tt> by default) and run

<code>
bin/epadmin create
</code>

You will get the following prompts (note that when you see something in [square brackets], it's the default value and can be selected by simply hitting enter)

* Archive ID - the system name for your archive. It's probably a good idea to think of something short and memorable. Once entered, an <tt>archive/<archive_id></tt> directory will be created, and the standard configuration files will be copied in.
* Configure vital settings - Hit enter to say 'yes'. This will lead to more prompting about core settings:
** Hostname - What someone will type into a web browser to get to your archive. Make sure that your systems team have a DNS alias pointing to your server for this.
** Webserver Port - Which port to you want to serve the archive on? The default is 80, so unless you can think of a good reason not to, just hit enter to accept the default.
** Alias - You can enter any number of aliases that will take users to this archive. Enter a '#' when you don't want to enter any more. You could have your archive served on <tt>eprints.myorganisation.org</tt> and <tt>eprints.myorg.org</tt>. As with the Hostname, your systems team need to be informed about these aliases too.
** Administrator Email - Enter the email address of the repository administrator. This will allow your repository users to send email to the right person.
** Archive Name - The full name of your archive. By default, this will be used on many of the pages, and in the title bar of the browser.
** Write these core settings - If you don't say 'yes', then you entered all that data for nothing.
* Configure database - EPrints makes extensive use of a MySQL database. Enter 'yes' to configure this.
** Database Name - The internal name of your database. It makes sense to use the Archive ID for this, but you don't have to. You don't need to create this database, epadmin will do it for you.
** MySQL Host - The address of the server that the database is running on. If the database is on the same machine as the EPrints installation, enter 'localhost'.
** MySQL Port - You probably don't need to enter a value. If you have problems connecting to the database, talk to your systems team.
** MySQL Socket - As with MySQL Port, it's unlikely that you need to enter anything.
** Database User - The username with which to log into the MySQL Database. You don't need to create this user, epadmin will do it for you. If you enter a MySQL username that already exists, it will be overwritten by epstats.
** Database Password - The password for the Database User.
** Write these database settings - You should write them, or you'll lose them.
** Create database <Database Name> - Say yes, and epadmin can create the database and populate it with all the right tables. If you've already created a database and a user for this archive, say no.
** MySQL Root Password - To create the database and the user, epadmin needs the MySQL Root Password. This is not saved anywhere. It is used to log into mysql, create the database and create the user with the right access rights. The password is then forgotten.
** Create database tables - say yes to have epadmin create all the database tables.
* Create an initial user - It's a good idea to create a user account for yourself at this point.
** Enter a username - The username you will use to log into EPrints in your browser.
** Select a user type (user|editor|admin) - There are three levels of user in EPrints. You probably want to be an administrator, so enter 'admin'.
** Enter Password - A password for this user. Remember to choose a password that will be hard for someone else to guess.
** Email - Enter your email address so that administrators can get in contact with you.
** Do you want to build the static web pages - There are a number of pages in EPrints which change very rarely. These are the static pages. The Home page and the About page are examples of static pages. Stylesheets are also static. These pages need to be built, so say 'yes'.
** Do you want to import the LOC subjects - If you will be using the Library Of Congress subject hierarchy, say 'yes'. Otherwise you will need to create your own subject hierarchy.
* Do you want to update the apache config files? (you still need to add the 'Include' line) - Your archive has a number of files which it uses to configure the web server. These should be updated, so say 'yes'.
* Before exiting, epadmin will display information about configuring the webserver.

Open a browser, and enter the hostname in the address bar. You should see your new archive, ready to be [[Branding with confidence|branded]].

If you want to add some more users, use the command <tt>epadmin add_user <repository id></tt>

===Modifying the Default===

The default document types and metadata in have been optimised for a repository of research output. It is up to you if this is sufficient. Adding new document types and modifying the metadata are discussed elsewhere.

==Running a Live Archive==
===Creating a crontab===
When you create an archive it will start out as a development system while you learn how to set it up (and your manager keeps changing his mind) but at some point (hopefully) you will declare your archive open for business.

At this point you should schedule certain scripts to run periodically. The best way to do this is to use "cron" which is an integral part of most UNIX systems.

To set up cron, run (as the eprints user):

<code>
% crontab -e
</code>
Exactly what to add to the cron table is described in the following sections - "Browse Views" and "Subscriptions".

There should be one set of crontab entries per archive.

===Backups===
You should also have made sure that the system is being properly backed up. This is gone into in more detail [[Backups|elsewhere in the documentation]].

===OAI===
We would also encourage you to configure the OAI support for your archive and register it.

====Configuring====

The setting for OAI are held in the <tt>oai.pl</tt> file, in the <tt>eprints3/archives/<archive id>/cfg/cfg.d/</tt> directory. This is a perl file, but don't let that daunt you. Some of the settings are set to sensible defaults. This guide cover the essentials. Feel free to use your favourite text editor instead of pico.

At the command prompt, backup then open the file:
>cd /opt/eprints3/archive/<archive id>/cfg/cfg.d
>cp oai.pl oai.backup
>pico oai.pl

The following need to be changed:

<strong>The archive ID</strong>. This needs to be unique, so check that it doesn't already exist at http://www.openarchives.org/.

Find the following line in oai.pl:
$oai->{v2}->{archive_id} = "generic.eprints.org";
And change generic.eprints.org to something which identifies your repository.

<strong>Content Description</strong>. What does your repository contain? Write a description, then find the lines:
$oai->{content}->{"text"} = latin1( <<END );
OAI Site description has not been configured.
END
Do not modify the first or last line in any way. Simply put your new text in the place of the middle line. This text can be as many lines as you wish, but it <em>must not</em> contain the word "END" at the start of a line.

<strong>Policies</strong>
Next you need to define a number of policies which will define how your repository may be used. It may be helpful for you to visit http://www.opendoar.org/tools/en/policies.php which has a step-by-step process to create these policies. It will even output EPrints 3 configuration code. which you can then copy and paste into the oai.pl file. These policies are:

* Metadata Policy
* Data Policy
* Submission Policy

These are updated in exactly the same way as the <strong>Content Description</strong> section. Just look for the following lines:

*$oai->{metadata_policy}->{"text"} = latin1( <<END );
*$oai->{data_policy}->{"text"} = latin1( <<END );
*$oai->{submission_policy}->{"text"} = latin1( <<END );

====Registering====

Once you register your archive (at http://www.openarchives.org) various search systems will be able to collect the metadata (titles, authors, abstract etc.) and allow more people to find records in your archive.

See http://www.openarchives.org/ for more information on the OAI protocol. For more information setting up the OAI interface archive see the section in this documentation about Configuring an Archive.

==Browse Views==
Once every so often you should run the <tt>[[generate_views]]</tt> script on each archive in your system to regenerate the browse views section of the site.

This is a set of static pages. By default one per subject, and one per year (only years with papers in that year not EVERY year ever!). Some users prefer to browse the system than search it. This also gives search engines a way to reach, and index, the abstract pages.

See the <tt>[[views.pl]]</tt> config notes on how to edit the views it generates.

===But I don't want this feature...===
If you don't want to use this feature: don't, it's your archive. Remove the link from the template and front page. Don't run the generate_views script.

===Setting it up===
This is best done by using the UNIX "cron" command (as user "eprints"). Cron will email "eprints" on that machine with the output, so best use the --quiet option so it only bothers you with errors.

How often you want to run this depends on the size of your archive, and how fast the contents changes. This feature is roughly order "n". Which means if you double the number of items in your archive then you double the time it takes to run (ish).

Once an hour would seem a good starting point. If your archive gets real big, say more than 10000 records, then maybe once a day is more realistic - the one thing that you don't want to happen is for a new generate_views to start before the old one finishes as they will mess up each others output.

Run generate_views on the command line to find out how long it takes.

and add the line

<code>
23 * * * * /opt/eprints3/bin/generate_views <archiveid>
</code>
This runs at 23 minutes past each hour. If you have more than one archive, don't make them all start rebuilding stuff at the same time, stagger it. Otherwise once an hour everything will slow down as it fights to run several intensive scripts at once.

See the crontab man page for more information on using cron.
>man 5 crontab

==Alerts==
Alerts provide a way in which users of your system can receive regular updates, via email, when new items are added which match a search they specified.

To automate sending out these alerts you must add some entries in the crontab (as for views). You need one set of these per archive.

For example (with dookuprints being the name of the archive):

<code>
# 00:15 every morning
15 0 * * * /opt/eprints2/bin/send_alerts dookuprints daily
# 00:30 every sunday morning
30 0 * * 0 /opt/eprints2/bin/send_alerts dookuprints weekly
# 00:45 every first of the month
45 0 1 * * /opt/eprints2/bin/send_alerts dookuprints monthly
</code>
Note the spacing out so that all 3 don't start at once and hammer the database. You may wish to change the times, but we recommend early morning as the best time to send them (midnight-6am).

Generate views

2007-03-21T14:20:26Z

Fmccown: Initial article

{{dirs}}

The <tt>generate_views</tt> script generates the static pages for an archive. It can be ran like so:

<code>
/opt/eprints3/bin/generate_views <archiveid>
</code>

The <tt>generate_views</tt> script should be ran on a regular basis to allow users to browse your repository by year or subject. You may find it useful to setup a cron job to automate running this script. See [[Getting_Started_with_EPrints_3#Browse_views|Browse views]] for more information.

Generic Linux Installation

2007-03-21T14:04:28Z

Fmccown: Link to Running epadmin

{{development}}
{{manual}}
==Installation==
(If you are upgrading an existing installation of eprints please see the section on upgrading elsewhere in this manual.)

EPrints needs to be installed as the same user as the apache webserver runs as. We suggest you install it as user "eprints" and group "eprints". Under some UNIX platforms, creating a user and group can be done using the "adduser" command. Otherwise refer to your operating system documentation.

Unpack the eprints tar.gz file:

% gunzip eprints-3.something.tar.gz
% tar xf eprints-3.something.tar

Now run the "configure" script. This is a /bin/sh script which will attempt to locate various parts of your system such as the perl binary. It will also check your system for required components.

% cd eprints-3.something
% ./configure

By default the system installs as user and group "eprints". You will need to change this if you are not installing as either "root" or "eprints".

The configure script accepts a number of options. All are optional. The most important are:

; --help : List all the options (many are intended for compiled software and are ignored).
; --prefix=PREFIX : Where to install EPrints (or look for a version to upgrade). By default /opt/eprints3/
; --with-perl=[PATH] : Path of perl interpreter (in case configure can't find it, or you have more than one and want to use a specific one).
; --with-user=[USER] : Install eprints to run as USER. By default "eprints".
; --with-group=[GROUP] : Install eprints to run as GROUP. By default "eprints".
; --with-virtualhost=[VIRTUALHOST] : Use VIRTUALHOST rather than * for apache VirtualHost directives.
; --disable-diskfree : Disable disk free space calls. This will be automatically set if configure fails its tests for the df call.
; --with-toolpath=[PATH] : An alternate path to search for the required binaries.

Once you are happy with your configuration you may install eprints by running install.pl:

% ./install.pl

Now you should edit the configuration file for your copy of apache. This is often <tt>/usr/local/apache/conf/http.conf</tt> or <tt>/etc/httpd/conf/httpd.conf</tt>

Add this line: (If you didn't install eprints in <tt>/opt/eprints3/</tt> replace that with the location on your system).
Include /opt/eprints3/cfg/apache.conf
Note that this file is only available after you created your archive via <tt>epadmin create</tt>. See [[Getting_Started_with_EPrints_3#Running_epadmin|Running epadmin]] for more information on creating an archive.

You may also wish to change the user and group apache runs as. The user ''must'' be the same as the user you installed eprints as. We recommend:

User eprints
Group eprints

Bin/

2007-03-17T18:06:54Z

Fmccown: Link to export

{{dirs}}

Command-line tools. These are used either directly from the command line, or set to be run every so often, using cron.

Use the --man option on the command line to get more information about these tools.

eg.
# /opt/eprints3/bin/export --man

*[[EPrints_Directory_Structure/eprints3|eprints3]]/bin/
** '''epadmin''' - Perform admin tasks including creating repositories.
** '''epindexer''' - UNIX script to start the EPrints indexer when the server reboots. Do not call directly.
** '''explain_sql_tables''' - Gives a brief summary of the purpose of each SQL table.
** '''[[EPrints Directory Structure/eprints3/bin/export|export]]''' - Export data from the system using an export plugin.
** '''generate_abstracts''' - Update all the Metadata-Summary pages. (The page for a single EPrint which links to the documents)
** '''generate_apacheconf''' - Update the apache configuration files.
** '''generate_static''' - Update all the static web pages.
** '''generate_views''' - Update all the /view/ pages.
** '''import''' - Import data from a file using an import plugin.
** '''import_subjects''' - Import the subject tree from a text file or XML file.
** '''indexer''' - This is a daemon which runs in background and indexes the words in documents, titles, abstracts etc. so that they can be searched.
** '''lift_embargos''' - This script should be run once a day. It removes security on documents which embargo date has passed.
** '''list_user_emails''' - This just outputs all the users emails as a text file. Handy for making a mailing list.
** '''make_latest''' - Makes a file for the specified archive with latest items. (still a bit experimental in 3.0)
** '''send_alerts''' - This should also be run daily, weekly and monthly with the appropriate options. Sends out saved search emails.
** '''startup.pl''' - Used by apache to load modules for mod_perl. Does not do anything useful on the command line.

Repository configuration

2007-03-02T18:56:27Z

Fmccown: /* XHTML */ Some cleanup

{{development}}
{{manual}}
==EPrints Archive Configuration==
This section describes all the configuration files in an single archive in the EPrints system.

===Primary archive configuration file===
Once you have created an EPrints archive the information you entered is placed in an XML file in /usr/local/eprint2/archives/ with the name ''archiveid''.xml - this file is documented later in this section.

===Archive configuration directory===
The bulk of the archive configuration is copied from /opt/eprints2/defaultcfg/ into the archives own configuration directory (usually /opt/eprints2/archives/''archiveid''/cfg/ This directory will usually contain the following files and directories:

; '''apache.conf''' : This file is generated by '''generate_apacheconf'''. See the documentation of '''generate_apacheconf''' for more information.
; '''apachevhost.conf''' (added v2.2) : This file is generated by '''generate_apacheconf'''. See the documentation of '''generate_apacheconf''' for more information.
; '''ArchiveConfig.pm''' : The general configuration items which don't fit anywhere else are in this perl module. It is described fully later in this section of documentation. This module "requires" the other 5 perl modules. They are in seperate files to make them easier to get to grips with.
; '''ArchiveMetadataFieldsConfig.pm''' : This module configures the metadata fields and the default values.
; '''ArchiveOAIConfig.pm''' : This module configures how the archive exports itself via the Open Archives protocol.
; '''ArchiveRenderConfig.pm''' : This module contains subroutines which handle rendering the data into XHTML (mostly) for display as webpages.
; '''ArchiveTextIndexingConfig.pm''' : This module handles turning UTF8 text strings into lists of index words for free text searches.
; '''ArchiveValidateConfig.pm''' : This module contains subroutines which check the metadata for problems.
; '''auto-apache.conf''' : This file is generated and overwritten by '''generate_apacheconf'''. Do not edit it directly. See the documentation of '''generate_apacheconf''' for more information.
; '''citations-''languageid''.xml''' : One of these files for each ''languageid'' supported by this archive. These XML files describe how to turn metadata for an item into a citation (with markup). They are described fully later in this section of documentation.
; '''entities-''languageid''.dtd''' : One of these files for each ''languageid'' supported by this archive. These DTD files are generated automaticly just before eprints loads the archives configuration and should not be edited directly.
; '''metadata-types.xml''' : This XML file describes the various types of eprints, users etc. and which metadata fields are required or relevant to each. It is described fully later in this section of documentation.
; '''phrases-''languageid''.xml''' : One of these files for each ''languageid'' supported by this archive. These XML files contain all the phrases which are specific to this archives such as the titles of metadata fields. They are described fully later in this section of documentation.
; '''ruler.xml''' : This XML file just contains the horizontal divider used in webpages created by the system. It is described fully later in this section of documentation.
; '''static/''' : This directory contains the data needed to create the static webpages such as the homepage, and about page. It is described fully later in this section of documentation.
; '''subjects''' : This file contains the initial subjects for the system. It is described fully in the documentation for '''import_subjects'''.
; '''template-''languageid''.xml''' : One of these files for each ''languageid'' supported by this archive. These XML/XHTML files describe the outline for webpages for this system. They are described fully later in this section of documentation.

==XML Config Files in EPrints==
This section contains some general information about the XML archive config files: template, phrases, ruler and citations. metadata-types.xml uses XML but these comments do not apply.

===XHTML===
These files use HTML elements (and other elements too). XHTML is a fairly new version of HTML which is backwards compatable with HTML 4 but written using XML, not SGML. This means that it is much stricter but less ambiguous and easier to parse and modify. Assuming you know HTML, the main differences are as follows:

; All tags must be closed : All elements must be closed, even ones such as <li>. Tags which do not have a close tag in HTML, like <tt><br></tt> or <tt><img src="foo"></tt> still must be closed eg. <tt><img src="foo"></img></tt> - this can be abbreviated as: <tt> <img src="foo" /></tt>
; All tags and attributes must be lower case : Self explanitary.
; Strict definition of what tags may appear within others : Not actually checked by EPrints. It will let any rubbish past as long as it's valid XML. But that's no reason to be naughty.
; All attributes must be wrapped in quotes : In HTML the values of attributes do not have to be wrapped in quotes, but in XML (and therefore XHTML) they do.
; All attributes must have a value : In HTML some attribues do not require a value, for example <tt><hr noshade></tt> In XHTML it is represented as <tt> <hr noshade="noshade" /> </tt>

So in summary, the HTML:
<code>
<img SRC=someurl>
<hr NOSHADE WIDTH=2>
<P>Foo bar</P>
</code>
should become in XHTML:
<code>
<img src="someurl" />
<hr noshade="noshade" width="2" />
<p>Foo bar</p>
</code>
And that's more or less it. See http://www.w3c.org/ for a complete description.

===Language specific files.===
phrases, template and citations have one instance per supported language. This allows the system to generate pages and emails in more than one language. Supporting a new language will require translating the all the english in the english config files currently shipped. If you do intend it do this (lots of work!) please get in touch with the eprints admin so that we can avoid duplicated effort.

===Extra Entities===
The XML files all use a DTD which defines a few extra entities. Entities are items in XML (or HTML) which start with "&" and end with ";" like &amp;. These additional entities come from the entities DTD file created by generate_entities. One DTD is created per language, although currently the only variation is the archive name.

; &archivename; : The name of the archive in the current language.
; &adminemail; : The administrators email address.
; &base_url; : The base URL of the system (without a trailing slash)
; &perl_url; : The base URL of the CGI directory (without a trailing slash)
; &frontpage; : The URL of the system homepage.
; &userhome; : The URL of the user homepage.
; &version; : The current EPrints version.
; &ruler; : The XHTML of the standard divider.
; Any XHTML character entity (since EPrints v2.1) : You may now use any XHTML character entity, eg. <tt>&nbsp; &eacute; &euro;</tt>.
; User configured entities : You can generate your own entities by modifying the function which generates them in ArchiveConfig.pm

None of these entities are not available in the citations file or the ruler file.

===Name Spaces and XHTML===
These files contain a mixture of custom tags and XHTML. To keep these distinct the XML files contain a name space definition in the first element. The pratical upshot is that all EPrints own tags have the prefix "ep:". The namespace information is actually ignored by the current version of the eprints system.

example of mixed tags (and entities):

<code>
<ep:phrase ref="lib/session:contact"><p>Feel free to contact
<a href="mailto:&adminemail;">&archivename; administration</a>
with details.</p></ep:phrase>
 
eprints elements: phrase
xhtml elements: p, a
eprints entities: archiveemail, archivename
</code>

==The Primary Archive Configuration File==
This XML file appears in the <tt>archives/</tt> directory, usually <tt>/opt/eprints2/archives/</tt>, it describes the most very basic details about the archive. It is generated (and modified) by configure_archive and will not normally need to be edited.

EPrints looks in this directory for XML files and attempts to load them all when starting the webserver.

This file should be chmod'd so that it can not be read by random users as it contains the database password.

The top level element is "archive" which has the attribute "id" which is the id of the archive. It should be the same as the filename. If this file is foo.xml then the id should be foo.

<tt> <archive> </tt> contains a list of XML tags enclosing some text. eg.

<code>
<host>stoatprints.org</host>
</code>
The following tags are expected in no special order:

; <host> : The hostname of this archive.
; <alias redirect="''yes-or-no''"> : This is optional and may be repeated. It has the attribute "redirect" which may be set to yes or no. This controls what virtual hosts are supported and if they should redirect to the main <host>.
; <language> : The ISO id of a language supported by this archive. Repeatable. One of these should also be the defaultlanguage. See below.
; <port> : The port number that the server is running on. Usually 80.
; <urlpath> : The directory from the root of the server name. Usually <tt>/</tt>
; <archiveroot> : The filesystem path of the rest of the archive configuration.
; <configmodule> : The path to the perl module which does the main configuration (ArchiveConfig.pm)
; <dbname> : The name of the MySQL database. Usually the same as the archive ID.
; <dbhost> : The host on which MySQL is running. Usually localhost.
; <dbport> : An optional MySQL port, if it's not the standard one. Should be empty if we are to use the default.
; <dbsock> : An optional MySQL socket. Should be empty if we are to use the default.
; <dbuser> : The username to use when connecting to MySQL, usually "eprints".
; <dbpass> : The password to use to connect to MySQL.
; <defaultlanguage> : One of the supported language. This is the default for this archive.
; <adminemail> : The email address of the archive administrator. I strongly suggest that this is an alias rather than a personal email address. If all your webpages contain "bob@footle.edu" and bill takes over from bob you would have to regenerate every page with "bill@footle.edu". Much better to set up an email alias or forward from "archive-support@footle.edu" and point it at bob (for now). Heed these words spoken from grim experience!
; <archivename language="''langcode''"> : The name of the archive. This has an attribute "language" the value of which is an iso language id. There should be one of these archivename elements per supported language. eg.

<code>
<archivename language="en">White Lemur</archivename>
<archivename language="fr">La Archive d'Lemur Blanc</archivename>
</code>
(apologies to the french, human languages aren't my strong suit)
; <securehost> (since v2.2) : Used for experiemental https support.
; <securepath> (since v2.2) : Used for experiemental https support.

==ArchiveConfig.pm==
This module imports the other 5 perl modules. It allows lots of little tweaks to the system, which are all commented in the file.

It includes options to hide various features you may not want and to customise the browse, search and subscription functions.

Also you can customise what each type of user can and can't do, and how they authenticate their passwords.

This configuaration file contains perl methods which are called when a session starts and ends, to log things, to generate the entities for the entities file and security on non public files.

===Browse Views===
The browse views are generated by the script "generate_views" and what that script does is configured by the "browse_views" item in the config.

It is a reference to a perl array [], each item of which is a hash {}.

The hash has 3 required properties and a number of optional ones.

; id (required) : The ID of this view - the view will be placed in a subdirectory of /views/ of this name. The ID is also used to identify the full name of this view in the phrase file. <tt> id=>"foo" </tt> would find it's title in the phrase "viewname_eprint_foo"
; fields (required) : The list of the names of the fields to browse, seperated by a slash "/". This should normally be a single field unless you want to merge the values of two fields. The id part of a field may be specified by appending ".id" to the fieldname.
; order (required) : A list of fields to sort by in order of priority, sepearted by slashes "/". A minus sign prefixing the fieldname "-" indicates reverse sorting on that field.
; allow_null : Should we make a page for the "unset" condition? A page for items which do not have a year set may be useful. But for other fields this may be meaningless. Set it to 1 for true.
; include : Generate a file for every value, ending in ".include" which contains the XHTML of the citations of records and the number of records, but without wrapping the site standard template around it.
; nohtml : Normally the system generates a page like that described for "include" with a .html suffix and the site template. If nohtml is set to 1 then it won't.
; citation : Normally the citation used is that for the "type" of eprint. If this is set then that citation (from the citations file) will be used for all items. This allows for some clever stuff if you want to make page which can get sucked into another website.
Normally the system puts a paragraph tag around each citation, but if you use a custom citation this will not happen.
; nocount : Do not include the count of how many items at the top of the page.
; nolink : The system generates an <tt>index.html</tt> in <tt>/view/</tt> with a list of all the browse views available. Setting nolink to 1 will hide this item.
; noindex : Do not generate an <tt>index.html</tt> file in <tt>/view/''foo''/</tt> listing all the values of the view and linking to their respective pages.
; notimestamp (since v2.2) : Do not add the timestamp at the bottom of the view page.
; hideempty (since v2.2) : Only applicable to subjects. This option will supress subjects which do not have any records in. This is useful on "young" archives which look very empty if you have a large subject tree and only a few records, and those clustered in 3 or 4 subjects.

The most common view is to browse by subject:

<code>
{ id=>"subject", allow_null=>0, fields=>"subjects",
order=>"title/authors", hideempty=>1 }
</code>
A more complex view generates a view on author & editor ID's which are not advertised but may be captured by some other software to build staff CV pages.

<code>
{ id=>"person", allow_null=>0, fields=>"authors.id/editors.id",
nohtml=>1, nolink=>1, noindex=>1, include=>1,
order=>"-year/title" }
</code>
For my example person id "wh" this will generate a webpage called /view/person/wh.include (and one for each other value of authors or editors ID's) which can be captured by an external automated system.

===User Privs===
The user permission configuration allows you to set what types of user can and can't do. The user home page will only show a user options which they can do.

New types of user, and which data about themselves they can edit is set in metadata-fields.xml.

Permissions are set by "type" of user. By default there are 3 kinds of user: "user", "editor" and "admin".

Admin can, by default, do everything.

; subscription (since EPrints v2.1) : If included then this kind of user can create subscriptions.
; set-password : Reset their password via the web registration system.
; deposit : Submit items into the archive.
; view-status : View the archive status page.
; editor : User can edit then approve submitted items into the main archive, or delete them, or return them to sender. Also can remove items from the archive back into the edit buffer for corrections, and move records into the deleted table (delete them).
; staff-view : User can perform a "staff search" of user or eprint records and view ALL the metadata.
; edit-subject : User can edit the subject tree via the online interface.
; edit-user : User can edit other users records.
; change-email : User can change their email address via the web interface. This is safer than allowing them to edit it directly as it ensures they cannot set it to an address which they recieve (it mails them a confirmation pin number)
; change-user : This allows the sinister feature which lets you log in as someone else. It still requires a password. This is useful if you want to perform admin tasks as a super user, then log-in as a normal user to deposit items.
; no_edit_own_record (since v2.2) : This supresses the "edit my user record" option. This may be useful if you disable web-registration and import the user records from some other database.

==ArchiveMetadataFieldsConfig.pm==
===Fields Configuration===
Metadata is data about data. The information which we store to describe each record (eprint) in the system. Users also have metadata.

This module is the configuration for the metadata. This is probably the most important part of the system.

See the chapter on metadata for all the configuration options.

===Defaults===
This section of the file contains subroutines which are called to set default values for Users, Documents and EPrints.

===Automatics===
These functions let you set automatic fields. This allows you to make fields which are updated automatically each time the item (User/EPrints/Document) is commited to the database.

This allows you to create "compound" fields. Such fields are created by processing the values of other fields rather than being edited directly.

For example, if you wanted to make an automatic int field which contains the ''number'' of authors, you could add the following to set_eprint_automatic_fields:

<code>
# no authors at all will be undef, not [] so check first
if( $eprint->is_set( "authors" ) )
{
my $auths = $eprint->get_value( "authors" );
$eprint->set_value( "authcount" , scalar @{$auths} );
}
else
{
$eprint->set_value( "authcount" , 0 );
}
</code>
==ArchiveOAIConfig.pm==
This module configures how the archive exports its data via the OAI protocol.

For more inforamtion on the how and why of OAI see http://www.openarchives.org/

OAI allows a harvestor to request the metadata from your archive and other archives to provide a federated search. The next time the harvestor harvests your archive it only has to ask for items which have changed or been added since last time it asked.

The current version of EPrints supports OAI v2.0. OAI version one is no longer supported.

The base URL for your OAI v2.0 interface will be http://archivepath/perl/oai2

If you want to use the OAI system then you need to fill in the blanks, such as policy and the OAI-id of the archive.

You may create OAI sets in a similar manner to "browse views" in ArchiveConfig.pm.

If you want to change the way that an EPrint is mapped into Dublin Core then edit the make_metadata_oai_dc - which returns a DOM XML object.

To add a new metadata type you need to add a new mapping function and add entries to the namespaces, schemas and functions items near the top of the file.

==ArchiveRenderConfig.pm==
This module contains fuctions which turn data into XHTML for displaying on the web.

If you want to change the way a user info page, or an eprint "abstract" page is rendered then here's the place to do it.

There are also "full" versions of these functions which display all the internal variables and things. These are the views which the editors and admin see.

The XHTML is generated using DOM (Document Object Model), but eprints provides some functions for easily generating XHTML DOM. The only method of DOM you should need to use is appendChild - which adds an element to this element.

===EPrints API functions which return XHTML objects.===
Note, all text strings should be in UTF-8.

Example:

<code>
my $page = $session->make_doc_fragment();
my $h1 = $session->make_element( "h1" );
$h1->appendChild( $session->make_text( "Title" ) );
$page->appendChild( $h1 );
$page->appendChild(
$session->make_element(
"img",
src=>"/images/cheese.gif",
width=>128,
height=>53 ) );
</code>
$page now contains:

<code><nowiki>
<h1>Title</h1><img src="/images/cheese.gif" width="128" height="53" />
</nowiki></code>

Many of the EPrints modules are fully documented. For an example try running:

<code>
% perldoc /opt/eprints2/perl_lib/EPrints/Archive.pm
</code>
The functions most useful to extacting and rendering information are documented here:

; <tt> $session->make_text( $text ) </tt> : Returns a DOM object representing that text.
; <tt> $session->make_doc_fragment() </tt> : Returns a document fragment. This renders to nothing but is a container to which you can add stuff.
; <tt> $session->make_element( $name, %opts ) </tt> : Makes a simple XHTML element. %opts is an optional series of attributes.
To make <code><nowiki><h1 class="foo">...</h1> </nowiki></code> you would call:

<code>
$session->make_element( "h1", class=>"foo" );
</code>
; <tt> $session->render_ruler(); </tt> : Returns the default ruler for the archive (from ruler.xml).
; <tt> $session->render_link( $uri, $target ) </tt> : Returns the XHTML element (with URI properly escaped):

<code><nowiki>
<a href="uri"></a>
</nowiki></code>

Which you can appendChild stuff into. If $target is specified then a target attribute is included - to make it pop up a new window.
; <tt> $item->render_value( $fieldname, $showall ) </tt> : $item is either an EPrint, a User or a Document.
$fieldname is the name of the field you want to render. If $showall is 1 then ALL values are rendered in a multilang field.
; <tt> $item->render_citation( $style ) </tt> : Renders the citation of the item using the citation for the item's type from the citation file.
If $style is set then it uses the citation with that id instead.
; <tt> $item->render_citation_link( $style ) </tt> : This renders a citation as above, but links it to the url of the item.
; <tt> $item->render_description() </tt> : This renders a simple description of the item using the default citation for this dataset eg. for eprint it uses citation type "eprint".
; <tt> $session->html_phrase( $phraseid, %opts ) </tt> : Returns the item from the phrase file. If you don't care about supporting multiple languages then just use make_text instead, it's easier.
It looks first in the archive field from the current language.
Then in the archive phrase file for english.
Then is the system phrase file for the current language.
Then is the system phrase file for the english.
The %opts are a series of DOM elements to place in the "pin" items in the phrase file.

===Some other useful functions you may need===
; <tt> $item->get_value( $fieldname, $no_id ) </tt> : Returns the value of field $fieldname from the item. An optional second parameter may be set to 1 to return the value without the "id" part, to keep things simple.
; <tt> $item->is_set( $fieldname ) </tt> : Returns true if the field is set on this object, false otherwise.
; <tt> $eprint->get_all_documents() </tt> : Return an array of the document objects belonging to this eprint.

==ArchiveTextIndexingConfig.pm==
This module you probably won't need to change unless you want to modify how eprints does searches for words in strings.

When a record is added to the system eprints uses this module to turn a string into a list of values which are indexed. By default these are words with 3 letters or more except some predefined stop words. It also turns latin characters with acutes into the their plain ascii (no acute/grave) versions.

It then does the same with the search string and looks for these keys.

Example:

<code>
The rain in spain falls mainly on the plains.
</code>
Is turned (by default) into the keys:

<code>
rain spain fall mainly plain
</code>
Thus searching for "rain" or "plain" or "plains" or "MaiNlY" will all match this string.

You may wish to add your own "stop words". eg. If you are running an archive about badgers, a search for the word "badger" will return almost all the records.

At a more complex level you may wish to add handling for non-european character sets (I have no idea how well the default setting will work on these), or do "stemming" - removing "ed", "ing", "ies", "s" etc. from the end of words so that "land" will match "land", "landed", "landing" and "lands". (It current removes 's').

Another suggestion is using ''soundex'' or similar techniques to match words which sound similar.

Changing the indexing on a live system will require you to regenerate the indexes using the reindex script. (If you don't then some of the search results will be wrong).

==ArchiveValidateConfig.pm==
This module handles validating data entered by users. Each subroutine is described in more detail in the module itself.

Each subroutine returns a list of DOM elements, each of which describing a single problem. Any problems will prevent the user from continuing with editing until they correct the problems.

As with the rendering functions, if you don't care about making this work in more than one language then you can just make the DOM items by calling $session->make_text( "problem explanation" )

The eprint & document validation routines have a flag '''$for_archive''' which, if true, indicates that the item is being checked before going into the actual archive. You can use this to force an editor to enter fields which the user may leave blank.

===Validation Functions===
; '''validate_field''' : Called for all fields. Use it to check individual field values. By default checks that url's look OK.
; '''validate_eprint_meta''' : Check the metadata of an eprint. Use this to test dependencies between fields. eg. if you have a requirement that field "A" OR field "B" must be set.
; '''validate_eprint''' : Validate the whole eprint. The last part of the validation of an eprint.
; '''validate_document_meta''' : Validate the metadata of the document (as with eprint_meta)
; '''validate_document''' : Validate the whole document, files and metadata.
; '''validate_user''' : Validate a user record.

==citations-''languageid''.xml==
The ciations file describes how to render an item (eprint/user/whatever) into a short piece of XHTML. Each citation has a "type". There are 3 kinds of citation:

; default citation : This is a very short description of the item. Usually "the title or failing that, the id". The type id is just the name of the dataset. eg. "eprint"
; type citation : These are richer descriptions which vary between type of eprint, user or document. The type id is dataset_type eg. eprint_preprint.
; other citation : Used by custom browse views. Any name you like.

The citation file contains a list of citation elements:

<code><nowiki>
<ep:citation type="...">
</nowiki></code>
Each one may contain text and tags. The text may also include the names of fields in the record being rendered. These names should be between @ symbols. eg. @authors@ or @title@. These will be replaced with a rendered version of the value in that field. (if you need an actual @ symbol for some reason two @@ with nothing inside will be rendered as a single @).

Note. The @title@ style was introduced in EPrints 2.2. Before that this file used XML entities such as &title; but this caused problems and didn't solve any. Use of entities is still supported, but deprecated.

In addition you may use XHTML elements and the following elements in the eprints namespace. These elements are always removed but they control if their contents is kept or not. Conditional elements may be placed inside each other since v2.2.

; <tt> <ep:linkhere> </tt> : This element is replaced with an XHTML anchor linking to the item. If this citation is being rendered without a link then it is just removed (but not the contents).
; <ep:iflink> : The contents of this element are only preserved if we are rendering this citation as a link. Maybe an icon which you don't want if it's not a link.
; <ep:ifnotlink> : The opposite of iflink.
; <ep:ifset ref="fieldname"> : The contents of this element are only preserved if the field "fieldname" has a value.
; <ep:ifnotset ref="fieldname"> : The contents of this element are only preserved if the field "fieldname" does not have a value.
; <ep:ifmatch name="fieldname(s)" value="searchparam"> : This is the swiss army knife of the world of conditional rendering. It is also a bit complicated, and few people will need to use it. This actually works like a single search element. The attributes are:
;; name : This is the name of one or more fields, specified as in the search fields configuration. eg. "title/abstract"
;; value : This is a value to search for. Treated like the value entered in a search field.
;; merge (optional) : Can be ANY or ALL. Works like the match all? in a search form.
;; match (optional) : Can be IN, EQ, or EX. In, Equal or Exact. Exact on subjects means that subject, but not any below it in the heirarchy.
For example:

<code><nowiki>
@year@<ep:ifmatch name="year" value="-1949">
(approx)</ep:ifmatch>
</nowiki></code>

This will render (approx) after years before 1950. Neat eh?
; <ep:ifnotmatch name="fieldname(s)" value="searchparam"> : Like ifmatch but only includes the values inside if the search does not match.

==metadata-types.xml==
This file allows you to configure the types of eprint, user, document and document security level.

When you add a new type you should add it's name to the archive phrases file(s). The phraseid is "dataset_typename_typename" eg. "document_typename_pdf", and you should add a new citation to the citations file. Any fields which are not required but appear in the citation should probably be inside a <ep:ifset> so that you don't get see "UNSPECIFIED" if they are not, er, specified.

The main element is "metadatatypes". This contains a list of "dataset" elements each of which has a name attribute.

The "type" elements in user and eprint "dataset"s should contain a list of "field" elements. This describes the fields which may be edited for this type and the order that they appear on the form.

You may include system fields in this list, but be careful if you do.

===Multi-page metadata (2.3.0+)===
You may optionally add <page name="pagename" /> elements to the field list. These break the submission process into smaller stages. The pagename is used to identify the sub-page, for purposes of validation etc. Pages only have an effect on eprint types, not user, document etc.

See the section on paged metadata.XX

===Attributes for "field" element===
; name (May not be ommited) : The name of the metadata field.
; required : If set to "yes" then this field may not be left blank. Some system fields are always required no matter how this is set.
; staffonly : This field only appears on the "editor" edit eprint form, not the user one. Or, in the case of the user dataset, the staff edit-user page.

===The "security" dataset===
This is a handy place to define the security levels. The type with no name is special. It is the "public" security type. All other types will require a valid username and password. If that username is acceptable for a given document is decided by the can_user_view_document subroutine in ArchiveConfig.pm

===The "document" dataset===
By default eprints requires at least one of ps, pdf, ascii or html to be uploaded before an eprint is valid. You may change this list in ArchiveConfig.pm - any more complicated conditions will have to be checked in the eprint validation subroutine.

==phrases-''languageid''.xml==
This file contains a list of XML "phrasees". Everything eprints "says" to users is stored in this file and its system-level counterpart. If you want the site to run in more than one language, you need one phrase file per language.

The phrase file is XML and contains a toplevel "phrases" element. This contains the list of phrases.

Each phrase has a "ref" attribute to identify it and contains text and optionally some XHTML tags. It may also contain eprints entities such as &archivename; and also some phrases should contain "pin" elements, described below.

The phrases in the archive phrase file are specific to that archive, the system phrase file contains non-archive specific phrases. The id's of most of the phrases in the archive phrases are generated from the id's of the fields, datasets, types etc.

The archive phrase file contains: names of dataset types, names of metadata fields, help on entering each Ametadata field, the names of options in "set" fields, the description of different search ordering options, names of browse views, phrases used in the render and validation routines, mail which eprints sends out and phrases which override those in the system file.

===pins===
Some phrases need some "pin" elements to show eprints where to insert values. Usually pins don't contain any elements but occasionally they do when they represent what to place a link around.

===Overriding System Phrases===
If you don't like some of the phrases in the main system phrases file you can override them by creating a phrase with the same "ref" in the archive file.

Don't edit the system file, if you upgrade eprints to a newer version it will get over-written.

===Emails===
EPrints sends out emails when a user registers/changes their password, when a user changes their email, when a deposited item is rejected/deleted by an editor and when the system is low on resources. These mails can be customised in the phrase file.

Make sure you wrap your text in paragraph <p> tags. EPrints will automatically word wrap these in the email. <hr /> elements in a mail are turned into a line of dashes.

When eprints sends a mail it will send it as plain ASCII text, unless it contains latin-1 elements, in which case it will be latin-1 encoded. If it contains unicode characters not in the latin-1 charset then it will be utf-8 encoded.

==ruler.xml==
This file configures the horizontal divider which eprints uses, which is inserted in place of &ruler;

If you have no great dislike of <hr /> horizontal rulers then you can leave it alone.

You can't use entities like &frontpage; in ruler.

==The static/ directory==
This directory contains the static pages for the site - the frontpage, the help pages, images, the stylesheet etc.

<tt>static/</tt> contains one directory per language, eg. <tt>en</tt>. Plus a <tt>general</tt> directory which contains files which don't need translating like images and the stylesheet.

When you run the <tt>generate_static</tt> command it copies the files for each language, and the gerneral dir, into the static site for that language.

See the <tt>generate_static</tt> documentation for more details.

==subjects==
This file is not used by the core eprints system. It is used by import_subjects to set up the initial subjects. For more information see the instructions for import_subjects.

==template-''languageid''.xml==
This file is the shell of every page in the system. It is more or less a normal XHTML page but you can use the eprints &foo; entities in it and it should contain "pin" elements like a phrase. The pins it should contain are:

; <tt> <nowiki><ep:pin ref="title" /></nowiki> </tt> : This is where to put the title of the page. It can be used more than once - in the title in the page header and somewhere in the body. If placing it in the title in the head of the page you must use the additional attribute textonly="yes" which only works here. It removes images from the title (which can happen if using the "Latex" mode).
; <tt> <nowiki><ep:pin ref="head" /></nowiki> </tt> : This goes somewhere in the head of the page. It shows eprints where to insert the "meta" and "link" elements.
; <tt> <nowiki><ep:pin ref="pagetop" /></nowiki> </tt> : This goes at the top of the body. It is sometimes used as a "target".
; <tt> <nowiki><ep:pin ref="page" /></nowiki> </tt> : Where to place the bulk of the content of the page.