How to

HOW TO: Set up a Complex Custom View

NOTE: http://wiki.eprints.org/w/Adding_new_views is a better page to start with for newer version of EPrints.

Simple instructions are in the ArchiveConfig.pm section.

Example situation: On my main website www.foobars.ac.uk I have a page per research project, of which we have hundreds. Each project has a short unique id code, eg. "manticore". I have a field in my eprints archive (eprints.foobars.ac.uk) which is configured:

{
  name=>"projectcodes", 
  type=>"text", 
  multiple=>1
}

I add the following browse view:

{ 
  id=>"by_project", 
  allow_null=>0, 
  fields=>"projectcodes", 
  order=>"-year/title" 
}

This will generate a page http://eprints.foobars.ac.uk/views/by_project/manticore.html with a list of all papers in that project, we can link to that URL!

Making the Field link to the Browse Page

If you want a subject to link the subject browse page of that value, add the browse_link property to the field (and regenerate the abstracts if you want).

If you remove the browse view you should remove the browse_link or it will be a broken link.

Values rendered inside citations which are used to link to the main record will not link into the browse view for obvious reasons.

Including a view in another page

If you change that to:

{ 
  id=>"by_project", 
  allow_null=>0, 
  fields=>"projectcodes", 
  order=>"-year/title", 
  noindex=>1, 
  nolink=>1, 
  nohtml=>1, 
  include=>1
}

This will generate a view which is NOT listed on the /view/ page and it will not skip making the .html file and make a .include file per value. This will only contain the "count" of items and the XHTML of their citations. This can be used as part of a page on the http://www.foobaars.ac.uk/ site; either by using php and capturing it on-the-fly using readfile or scripting it with perl or NFS exporting the filesystem onto the main server (or just doing it all on one computer) and using server side includes to place it in a page.

Customising the way each item is cited

I want to list the project papers in a strict format in a table with 4 columns: title, author(s), year and an icon which links to the document abstract page...

I add some more options to the browse view:

{ 
  id=>"by_project",
  allow_null=>0, 
  fields=>"projectcodes", 
  order=>"-year/title", 
  noindex=>1, 
  nolink=>1, 
  nohtml=>1, 
  include=>1, 
  nocount=>1, 
  citation=>"project_table" 
}

Now I add a new citation to the citations config file:

<ep:citation type="project_table">
  <tr>
    <td>&title;</td>
    <td>&authors;</td>
    <td>&year;</td>
    <td>
      <ep:linkhere>
        <img src="http://www.foobars.ac.uk/images/paperlink.png" alt="view" width="32" height="64" border="0" />
      </ep:linkhere>
    </td>
  </tr>
</ep:citation>

That should generate for the manticore project, in the ".include" file (I've cut the contents of the "img" tag for readability:

<tr>
  <td>Making Stuff</td>
  <td>Guy, A.</td>
  <td>2001</td>
  <td>
    <a href="http://eprints.foobar.ac.uk/archive/00000923/">
      <img ... />
    </a>
  </td>
</tr>
<tr>
  <td>Eating Food</td>
  <td>Herring, Walter and Chips, Bob</td>
  <td>2000</td>
  <td>
    <a href="http://eprints.foobar.ac.uk/archive/00000445/">
      <img ... />
    </a>
  </td>
</tr>

A "CV" page - a list of all of Alices records

This is where the authors and editors field having an ID comes in handy.

Say we use local username to identify people in the "Person ID" fields, we can now set up a view:

{ 
  id=>"by_person", 
  allow_null=>0, 
  fields=>"authors.id/editors.id", 
  order=>"-year/title", 
  noindex=>1, 
  include=>1 
}

This will generate both .html pages and .include pages. An member of your organisation can get a list of their records either by linking to /views/by_person/alice.html (where alice is their username) or by snarfing the URL /views/by_person/alice.include into his own homepage.

HOW TO: Fields

Add a new Field

This covers adding a new field to a new system, not a live system. It is possible to add a new field to a live system but involves SQL hacking.

In this example we add a new "set" field called "local" which will have 3 options "yes", "no" and "partial" - this will indicate if the item in question was produced in our organisation or not.

Add the Field to ArchiveMetafieldConfig.pm 

Add the field to the appropriate part of ArchiveMetafieldConfig.pm (the "eprint" section in our example)

{ 
  name => "local", 
  type => "set", 
  input_rows => 1, 
  options => [ 
    "yes", 
    "no", 
    "partial" 
  ] 
}

input_rows being set to one will make it appear as a pull-down menu.

Add the Field to metadata-types.xml 

If you want the user to be able to edit this field for any or all types of eprint/user then you need to add it to each appropriate type in metadata-types.xml (this can be changed on a live system without any serious consequences).

<field name="local" required="yes" />

Add the Field Information to the Archive Phrase File(s) 

Normally we just need to add fieldname and fieldhelp, but this is an option field so we need to add names for each option. If we run the archive in more than one language then we add this to each phrase file (but in the appropriate language).

<ep:phrase ref="eprint_fieldname_local">Produced Locally</ep:phrase>
<ep:phrase ref="eprint_fieldhelp_local">Please indicate if this item was produced in the foo organisation, or not.</ep:phrase>
<ep:phrase ref="eprint_fieldopt_local_yes">produced locally</ep:phrase>
<ep:phrase ref="eprint_fieldopt_local_no">not produced locally</ep:phrase>
<ep:phrase ref="eprint_fieldopt_local_partial">only partially produced locally</ep:phrase>

Other things you may wish to change after adding a new field

Add it to the citations file 

This is optional, only do this if you want it to appear in the citated forms.

In our example case we only want this to appear when citing technical reports, so we change that entry to:

<ep:citation type="eprint_techreport">
  <ep:linkhere>
    &authors; <ep:ifset name="year">(&year;) </ep:ifset> &title;. Technical Report<ep:ifset name="reportno"> &reportno;</ep:ifset><ep:ifset name="department">, &department;</ep:ifset><ep:ifset name="institution">, &institution;</ep:ifset>. &local;.
  </ep:linkhere>
</ep:citation> 

All we've done is add &local;. to the end. It's not inside <ep:ifset name="local"> as it is a required field and will (should) always be set.

Add it to the the Abstract (or View-User) page. 

This is also optional. If you want it to appear on the web page for this item then edit ArchiveRenderConfig.pm and select the appropriate function, either eprint_render or user_render.

In our example we only want to mention items if an item was not produced locally. We'll add it below the documents and above the abstract...

Single language example:

if( $eprint->get_value( "local" ) ne "yes" )
{
     # don't need to "my $p" as it's done earlier.
     $p = $session->make_element( "p" );
     $p->appendChild( $session->make_text( "This item was " ) );
     $p->appendChild( $eprint->render_value( "local" ) );
     $p->appendChild( $session->make_text( "." ) );

     # Append our new paragraph to the page.
     $page->appendChild( $p );
}

Multiple-language example: If you want to make it handle more than language then we'll need to use the archive phrase file - we would add something like this to each languages file:

<ep:phrase ref="page:itemnotlocal">
  <p>This item was <pin ref="status" />.</p>
</ep:phrase>

And to the ArchiveRenderConfig.pm file:

if( $eprint->get_value( "local" ) ne "yes" )
{
  my $localmsg = $session->html_phrase(
    "page:itemnotlocal",
    status=>$eprint->render_value( "local" ) );
  $page->appendChild( $localmsg );
}

You may prefer to use this method even if you are only using a single language.

Add extra Validation Routines 

If you need to validate this field in a special way, add code into ArchiveValidateConfig.pm

Add it to the OAI metadata (eprints only) 

If this field can be rendered into Dublin Core (or other metadata formats you are using) then add it to the appropriate place in the ArchiveOAIConfig.pm file.

Add a browse view (eprints only) 

If you want to be able to browse this values items. See elsewhere in the docs for how to do this.

If you add a field you will need to run erase_archive and create_tables before you will see a change. EPrints will fail to run if you change the fields and do rebuild the tables.

HOW TO: Remove a Field

The quick answer is to say "the opposite of adding one".

Remove the Field to metadata-types.xml 

Removing it from here will mean that nobody can enter values for that field. Which is possibly enough, and means you can put it back later.

Remove the Field to ArchiveMetafieldConfig.pm 

This will remove it from the database ( and require a rebuild as with adding a field ).

Remove it from the phrase file(s) 

This is optional, unused phrases are just ignored.

Remove it from the citations file 

If it's used there.

Remove it from the the Abstract (or View-User) page. 

If it's used there.

Remove extra Validation Routines 

In the unlikely event you added some validation which looks at this field.

Remove it from the OAI metadata (eprints only) 

If it's being used. Fields used to generate the default dublincore are: title, authors, subjects, abstract, year and month. It also uses "type" which is a system field so you can't remove it!

Remove it from browse views (eprints only) 

If it's used there.

HOW TO: EPrint types

Add a new eprint type

Add the eprint type to metadata-types.xml. Some fields should probably be "required".

Add the name of the type to the phrase file.

Add a citation for this type to the citations file.

Remove an eprint type

Remove it from metadata-types.xml

You can remove it from the phrase file & citations but it won't hurt to leave it there.

HOW TO: Add a new document type

Add it to metadata-types.xml. This does not need any fields.

Add the name of the document type to the phrase file.

Add a citation for this document to the citations file.

If you want this to be one of the must-have-one-of document types then add its id to the list in ArchiveConfig.pm

If you want to do something "clever" on the abstract page then edit the ArchiveRenderConfig.pm file. If you don't then it will use the citation you created to render it in the list, as with PDF, HTML etc.

HOW TO: Add a Discussion Forum for Each EPrint

The UK Open University (open.ac.uk) have set up a service which allows you to create a discussion for every EPrint in your archive.

The really easy way to do this is to use their discussion server. If you want to run your own d3e server the software is available from http://d3e.sourceforge.net/

Using d3eprints.open.ac.uk

Just add the following code to the ArchiveRenderConfig.pm file just before the if( $has_multiple_versions ) bit.

Please note that this code is not internationalised.

#####################################
# Begin D3Eprints links

my $ol = $session->make_element( "ol" );
my $li = $session->make_element( "li" );
$a = $session->render_link(
  EPrints::Utils::url_escape( "http://d3eprints.open.ac.uk/disc.php?url=".$eprint->get_url ),
  "_top" 
);
$a->appendChild( 
  $session->make_text( "View public discussion of this document" ) 
);
$li->appendChild( $a );
$ol->appendChild( $li );

$li = $session->make_element( "li" );
$a = $session->render_link(
  EPrints::Utils::url_escape( "http://d3eprints.open.ac.uk/private/disc.php?url=".$eprint->get_url ),
  "_top" 
);
$a->appendChild( 
  $session->make_text( "Create private discussion of this document" )
);
$li->appendChild( $a );
$ol->appendChild( $li );

$table->appendChild( 
  _render_row(
    $session,
    $session->make_text( "D3Eprints discussion" ),
    $ol 
  ) 
);

# End of D3Eprints links
#####################################

HOW TO: Website Integration

Make the latest additions to your archive appear on your main website

The contents of the "latest" page - /perl/latest - can be included via a cron tab using wget and a server side include or using something like PHP's command to do:

readfile( "http://eprints.foo.org/perl/latest?mainonly=yes" );

The "mainonly=yes" flag is a hack which supresses the template of any eprints page in the /perl/ area so that it can be included, but it is most useful for "latest".

WARNING: If you have a script which imports 1000 records in one night then latest isn't currently bright enough to truncate the list so your homepage could get kinda messy.

RSS into HTML

If you want to turn any search into a dynamically generated list of references with a link back to the EPrints page, then use this. This solution uses PHP. So, you will need PHP enabled on the server.

Dependency: This code depends on MagpieRSS.

Original Context: It was developed for use in a Terminal4 'SiteManager' template, but can be used with almost no modification.

The code implements local caching of the generated HTML in a text file which is never more than an hour old, unless there is a problem with the server whereupon the last good cached version is used.

require_once('D:/website/[path to]/magpierss/rss_fetch.inc');
<span style="color: green; font-weight: bold">//set some variables here:</span>
$anchor = '<t4 type="meta" meta="html_anchor" />';
<span style="color: green; font-weight: bold"># All items in Terminal4's cms have an anchor - we like break it apart to get the Unique id, to name the cache file.</span>
$TTL = 3600;
<span style="color: green; font-weight: bold"># Time to live - one hour only.</span>
$feed = '<t4 type="content" name="RSS_Feed_URL" output="normal" modifiers=""  />';
$uniqueID = explode("\"", $anchor);
$filename = "./" . str_replace('.', '-', $uniqueID[1]) . ".txt";
<span style="color: green; font-weight: bold">#filename of cache - generated from unique id in T4 content management system.</span>
$max_items = <t4 type="content" name="MaxNumberToShow" output="normal" modifiers=""  />;
<span style="color: green; font-weight: bold"># $max_items = 30; // this is set in EPrints as well, will not exceed Eprints' own internal limit.</span>
$with_summaries = '<t4 type="content" name="ShowSummary" output="normal" modifiers=""  />'; # could be 'yes' or 'no'
$age = 0;
if(file_exists($filename)){
  $age = time() - filemtime($filename); 
}else{
  $fh = fopen($filename, "w");
  fwrite($fh, $news_feed);
  fclose($fh);
  $age = $TTL;
}

function getFromCache($f){	
  $fh = fopen($f, "r");
  $size = filesize($f);
  $data = fread($fh, $size);
  print $data;
  fclose($fh);
}
 
if($age >= $TTL){ 
  if($rss = fetch_rss($feed)){
    $items = array_slice($rss->items, 0);
    $find = array("/^\.?/");
    $replace = array(" ");
    $news_feed = "<ul class=\"rss_list\">\n";
    foreach ($items as $item ){
      if($count < $max_items){
        $news_feed .= "\t<li class=\"rss_item\">\n";
        $news_feed .= "\t\t<span class=\"rss_title\"><a href=\"" . $item['link'] . "\" target=\"_blank\">";
        $news_feed .= $item['title'] . "</a></span>\n\t\t<br />\n";
        if($with_summaries == 'yes'){
          $news_feed .= "\t\t<span class=\"rss_summary\">\n\t\t\t";
          $news_feed .= str_replace(($item['title'] . "."), "", htmlentities($item['summary'])) . "<br/>\n\t\t</span>\n";
        }
        $news_feed .= "\t\t<br />\n\t</li>\n";
        $count += 1;
      }
    }
    $news_feed .= "</ul>\n\n";
    echo $news_feed;
    $fh = fopen($filename, "w");
    fwrite($fh, $news_feed);
    fclose($fh);
  }else{
    getFromCache($filename);
  }
}else{
  getFromCache($filename);
}
<span style="color: green; font-weight: bold"># David Kane, Waterford Institute of Technology</span>

HOW TO: Add full text searching

EPrints does not support this natively but there are several options.

htdig, or similar software

There is plenty of software which will provide a full text search of a website. To add non-eprints cgi scripts to your site create a directory in the cgi dir:

mkdir /opt/eprints2/cgi/local

and place your scripts in there, they will have URLs under http://yoursite.com/perl/

Using an external search engine

This is very easy, but will only index public documents. Any search engine will work, but Google is a good choice. Google provide a site-search service which allows you to register with them and then have a form which searches your site using google and adds your logo and colourscheme to the results.

A really easy solution is to just make a form which links to our "google_site" script which just adds "site:yoursite.com" to the google request to limit the search results. The HTML for this would be something like:

<form action="/perl/google_site">
  Use Google to search this site:
  <input name="q" value="" />
  <input type="submit" name="go" value="Search" />
</form>

For other search engines; see their documentation for how to make a form to search only your site.

HOW TO: Make the referencetext field link to the items referenced

This should have been in the 2.2 docs but I didn't have time. Check the latest version of the documentation at software.eprints.org, if it's not there then bug me at support@eprints.org

HOW TO: Make the password controlled parts of the site use HTTPS

This should have been in the 2.2 docs but I didn't have time. Check the latest version of the documentation at software.eprints.org, if it's not there then bug me at support@eprints.org

HOW TO: Customise the way the the search results are formatted

This should have been in the 2.2 docs but I didn't have time. Check the latest version of the documentation at software.eprints.org, if it's not there then bug me at support@eprints.org

HOW TO: Reset your EPrints admin password [3.3]

To directly reset your password, log into phpMyAdmin and execute the following mySQL statement:

UPDATE user SET password = encrypt('newpassword') WHERE userid = 1;

This will effectively reset the EPrint admin password for user 1. Note that you can use this to reset the password of any user, although this is typically unnecessary as you should be able to simply log in as admin user (user 1), under which you have the ability to reset any user's password.