EPrints Control Format

EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects

---

XML Configuration: EPScript - Control Format (EPC) - Citation - Workflow - Phrase - Template - XPAGE (static pages)

EPrints Control

Output Tags

epc:print

<epc:print expr='expression' opt='key=value;key2=value2'/>

 <cite:citation xmlns="http://www.w3.org/1999/xhtml"
           xmlns:cite="http://eprints.org/ep3/citation"
           xmlns:epc="http://eprints.org/ep3/control">
     <epc:print expr="$item.citation('default')" />
 </cite:citation>

Outputs the result of the expression in the 'expr' attribute.

Rendering options may be passed in the opt attribute using a key=value form, with semicolons separating multiple options.

Any EPScript expression can be used. The most simple is just 'eprintid','title','creators' etc. You can also use values from the configuration files by using '$config{base_url}'.

Print in attributes using {}

Sometimes you may wish to insert a value into an XML attribute. eg. the "href" part of an anchor. Rather than a complicated system, but correct XML, we decide to go for something a bit more readable. Any {} pair in an XML attribute will be treated as a epc:print.

So you can do something like

<a href="http://eprints.badger.edu/cgi/myscript.pl?eprintid={eprintid}">run myscript on this eprint</a>

epc:phrase

simple:

 <epc:phrase ref='phraseid' />

with pins:

 <epc:phrase ref='phraseid'>
   <epc:param name='somepin'>Content</epc:param>
 </epc:phrase>

Outputs the content of the phrase refered to by 'ref'. Any necessary parameters may be set using the <epc:param> tag, with the contents inserted into the pin with the name corresponding to the name attribute.

Conditional Tags

epc:if

 <epc:if test='expr'>
 ...
 </epc:if>

Outputs any XHTML content and evaluates any EPrints Control structures within the epc:if block if the expression in the test attribute is true.

epc:choose, epc:when, epc:otherwise

 <epc:choose>
   <epc:when test='expr'> 
   ...
   </epc:when>
   <epc:when test='expr2'> 
   ...
   </epc:when>
   <epc:otherwise>
   ...
   </epc:otherwise>
 </epc:choose>

epc:choose allows for the construction of a complex conditional. Each epc:when block's 'test' attribute is evaluated, and the content of the block is returned if the result is true. If no expressions return true, the optional epc:otherwise block is returned. Note that no subsequent epc:when blocks are evaluated once the first block to return true is reached.

epc:comment

XML comments are not removed from the output when they are encountered in a citation or other EPScript.

<epc:if test="blah">
  <!-- only print blah if it exists -->
  <epc:print expr="blah" />
</epc:if>

will result in the comment appearing in the html source:

<!-- only print blah if it exists -->
This is Blah

Using an epc:comment block allows you to include comments that aren't rendered in the output:

<epc:if test="blah">
  <epc:comment> only print blah if it exists </epc:comment>
  <epc:print expr="blah" />
</epc:if>

Loops

Multiple values can be iterated over. For example.

  <epc:foreach expr="creators_name" iterator="name">
    ( <epc:print expr="$name" /> )
  </epc:foreach>

$index (3.2.0+)

Within a foreach block you can use $index to find what iteration of the loop is on. The first value is zero.

This can be used with the modulus "%" to add a strip effect, if wanted, eg.

<table>
  <epc:foreach expr="creators_name" iterator="name">
    <epc:if test="$index % 2">
      <tr class='odd'><td><epc:print expr="$name" /></td></tr>
    </epc:if>
    <epc:if test="!($index % 2)">
      <tr class='even'><td><epc:print expr="$name" /></td></tr>
    </epc:if>
  </epc:foreach>
  </table>

limit (3.2.0+)

You can set a limit of how many iterations to process using a "limit" attribute on the epc:foreach element. For example,

  <epc:foreach expr="creators_name" iterator="name" limit="3">

epc:debug (3.2.0+)

The epc:debug element has identical syntax to epc:print, but the result is sent to the error log -- either the command line, or to the apache error log.

  <epc:debug expr='expression' opt='key=value;key2=value2'/>

epc:set (3.2.0+)

This allows a variable to be set for any print or if elements within the epc:set. This is useful if creating the value has a notable cost which you wish to minimise.

$item.documents() requires some database access, and the results are not cached, so using this speeds things up.

  <epc:set name='docs' expr='$item.documents()'>

epc:list (3.3.17+ and 3.4.2+)

Allows multiple variables to be printed out with a common separator, where separator is not added if any variables are not set. Also allows a prefix and suffix to the list. E.g.

<epc:list prefix='[ ' suffix=' ]' join=" | ">
   <epc:item>First<</epc:item>
   <epc:item> </epc:item>
   <epc:item>Third</epc:item>
   <epc:item><epc:print expr="title"/></epc:item>
   <epc:item><epc:print expr="patent_applicant"/></epc:item>
   <epc:item>Sixth</epc:item>
</epc:list>

Produces:

[ First | Third | Test Title | UNSPECIFIED | Sixth ]

If the value inside the <epc:item> is empty or only contains whitespace (spaces, tabs, newlines and carriage returns) it will be ignored. If a variable is used that is not specified, such as patent_applicant, then this will still be displayed if the default value for an unspecified value is set (e.g. like UNSPECIFIED in the example above). To avoid this put an if test for the variable and the whole item will be ignored.