EPScript/Functions
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)
| EPScript | ||
Contents
Functions
Calling Functions
Functions can be called in two ways:
<when test="is_set( creators )">
or
<when test="creators.is_set">
These are interchangable, but it may be beneficial to use a specific form in some cases.
Boolean Functions
is_set
Returns true if the parameter is set, based on the following criteria:
- If the parameter is a string, it is set if it is not empty.
- If the parameter is a list or a complex structure, it is set if at least one value is set.
<when test="is_set( creators )"> ... </when>
yesno
Returns a yes or no string depending on whether the expression is true.
<print expr="yesno(is_set('abstract'))" />
String Functions
as_string
Converts variable into a string. Can be useful in phrases or for defining class or id attributes for HTML elements
<phrase ref="licenses_description_{license.as_string()}" />.
contains
Returns a boolean depending whether the string contains a particular substring.
<when test="title.contains('the')">
join
Returns the concatentation of strings with a particular joining character.
<when test="$list.join(':') = 'a:b:c'">
...
</when>
reverse
Returns the reverse of a string (i.e. 'abc' becomes 'cba').
<when test="type.reverse = 'tnetap'">
strlen
Gets the integer length of a string.
<when test="strlen(title) > 50"> ... </when>
substr
Returns the substring of a string
<when test="title.substr(0,3) = 'the'">
Integer Functions
add
Returns the addition of one number to another.
<when test="pages + 4 > 10">
divide
Returns the division of one number by another.
<when test="pages / 4 lt 10">
mod
Returns the modulus (i.e. remainder) of a number from a base (e.g 5 % 3 equals 2.
<when test="pages % 2 = 0">
multiply
Returns the multiplication of one number by another.
<when test="pages * 4 gt 10">
subtract
Returns the substraction of one number from another.
<when test="pages - 4 lt 10">
uminus
Returns the negative value of an integer (e.g. 1 becomes -1). This is a unary rather than binary operator like substract.
<when test="-rating gt 5">
Date Functions
datemath
Returns a date relative to the date provided, (e.g. two years ago).
<when test="date lt today().datemath( -2,'year' )">
today
Returns today's date
<print expr="today()" />
List Functions
array_concat
Concatenate multiple arrays into a single array
filter_compound_list
length
Returns the number of items in the list.
<if test="length(editors) gt 1">s</if>
one_of
Returns a boolean depenbding on whether a variable is one of a number of values.
<when test="type.one_of('article','conference_item','book')">
pretty_list
to_data_array
Data Object Functions
action_list
Returns an array of actions for a particular data object.
<foreach expr="action_list('eprint_summary_page_actions',$item)" iterator="action">
as_item
Treats a variable as an item so other data object functions can be applied to it.
<when test="$doc.property('eprintid').as_item().property('type') = 'thesis'">
control_url
Returns the control URL of a particular data object. (e.g. /cgi/users/home?screen=EPrint::View&eprintid=1234)
<a href="{$item.control_url()}">Download</a>
dataset
Returns the string for the dataset of the data object.
<when test="$item.dataset() = 'document'">
main_item_property
Get the property of parent data object.
<print expr="$doc.main_item_property('note')" />
property
Get the property of a data object
<print expr="$item.property('note')">
Returns an array of objects related to the current data object through a particular property.
<foreach expr="$doc.related_objects('http://eprints.org/relation/hasVersion')" iterator="rel">
subproperty (3.4.4+)
When you have a compound (non-multiple) field and want to print out just a sub-property of this field. E.g.
<print expr="compoundfield.subproperty( 'subfield2' )"/>
Will print field2 of the field named compoundfield. This currently only works for non-multiple compound fields.
to_dataobj (3.4.4+)
Will take the variable specified and will lookup this against the DataObj type specified using the particular field specified. E.g.
<epc:print expr="userid.to_dataobj( 'user', 'userid' ).property( 'username' )"/>
Will print the username of the user who is owner of the eprint. Where the first userid is the field in the EPrint DataObj, user is the dataset ID you want to lookup against and the second userid is the field in the User DataObj you want lookup against. The property function is then used to get the value for username from the retrieved user DataObj.
uri
Returns the control URI of a particular data object. (i.e. /id/<DATASET>/<ID>/, e.g. /id/eprint/1234/)
<a href="{$item.uri()}">Download</a>
url
Returns the URL for a particular data object.
<a href="{$doc.url()}">Download</a>
EPrint Object Functions
contact_email
Returns the contact email address for an EPrint object. This will only return a contact email address if the email_for_doc_request function is set.
<when test="$item.contact_email().is_set()">
documents
Returns a list of all the documents for an EPrint object.
<set name='docs' expr='$item.documents()'>
Document Object Functions
doc_size
Returns the size of the document (i.e. in bytes).
<print expr="$item.doc_size()" />
human_filesize
Returns the human-readable file size. Taking an integer number of bytes and converting into KB, MB, etc. (E.g. 258B, 125KB, 12MB).
<epc:print expr="$item.doc_size().human_filesize()" />
is_public
Returns a boolean for whether a document is publicly accessible.
<when test="$doc.is_public()">
thumbnail_url
Returns a URL string for a particular type of preview image for a document.
<print expr="$doc.thumbnail_url('lightbox')" />
User Object Functions
has_role
Returns a boolean for whether the user has a particular role.
<when test="$current_user.has_role('ref/set_dates')">
Render Functions
action_button
Returns an XHTML object for the button of a particular action on a data object.
<print expr="$action.action_button()" />
action_icon
Returns an XHTML object for the icon of a particular action on a data object.
<print expr="$action.action_icon()" />
action_title
Returns an XHTML object for the title of a particular action on a data object.
<print expr="$action.action_title()" />
citation
Renders the XHTML citation for a data object with a specified style. Encapsulated within a link to
<print expr="$item.citation('default')" />
citation_link
Renders the XHTML citation for a data object with a specified style, where the title is encompassed by a link to the data object.
<print expr="$item.citation_link('default')" />
dumper (3.4.4+)
Renders an XHTML pre element containing the type and serialization of a variable/metafield. Useful for debugging workflow/citation issues. Not particularly useful for data objects as dump will be too big to be rendered.
<print expr="creators.dumper" />
embed_video
Renders an XHTML object to render an HTML5 video preview for a document that is a video or audio file.
<print expr="$doc.embed_video" />
icon
Returns an XHTML object with thumbnail size icon preview of the document. It can be called with various options to determine what to do when you hover over or click on the icon.
<epc:print expr="$doc.icon('HoverPreview','noNewWindow','previewLeft')}" />
phrase
Returns an XHTML object for a phrase.
<print expr="phrase('lib/document:preview')" />
preview_link
Returns an XHTML object containing an anchor (i.e. <a href="..."></a> linking to a particular type of preview image for a document. This requires the citation link, the name of the set to preview and the type of preview image.
<print expr="$doc.preview_link($doc.citation_link('default'),'docs','lightbox')" />
render_value_function
Renders an XHTML object of the value of a field using a bespoke rendering functions
<print expr="$item.render_value_function('highlight_internal_authors', 'creators')" />
