Difference between revisions of "EPScript/Functions"

From EPrints Documentation
Jump to: navigation, search
(Switched back to basic navigatiom template)
m (→‎dumper (3.4.4+))
 
(8 intermediate revisions by the same user not shown)
Line 1: Line 1:
 +
{{formats}}
 +
 
{{EPScript}}
 
{{EPScript}}
  
Line 4: Line 6:
  
 
== Calling Functions ==
 
== Calling Functions ==
−
 
 
Functions can be called in two ways:
 
Functions can be called in two ways:
−
 
+
{{codesample|<pre>
−
{{codesample|
+
<when test="is_set( creators )">
−
<pre>
+
</pre>}}
−
<when test="is_set( creators )">
 
−
</pre>
 
−
}}
 
−
 
 
 
or
 
or
 +
{{codesample|<pre>
 +
<when test="creators.is_set">
 +
</pre>}}
 +
These are interchangable, but it may be beneficial to use a specific form in some cases.
  
−
{{codesample|
 
−
<pre>
 
−
<when test="creators.is_set">
 
−
</pre>
 
−
}}
 
−
 
−
These are interchangable, but it may be beneficial to use a specific form in some cases.
 
  
−
== Generic Functions ==
+
== Boolean Functions ==
  
 
=== is_set ===
 
=== is_set ===
−
 
 
Returns true if the parameter is set, based on the following criteria:
 
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 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.
 
* If the parameter is a list or a complex structure, it is set if at least one value is set.
 +
{{codesample|<pre>
 +
<when test="is_set( creators )">
 +
  ...
 +
</when>
 +
</pre>}}
 +
 +
=== yesno ===
 +
Returns a <tt>yes</tt> or <tt>no</tt> string depending on whether the expression is true.
 +
{{codesample|<pre>
 +
<print expr="yesno(is_set('abstract'))" />
 +
</pre>}}
 +
 +
 +
== String Functions ==
 +
 +
=== as_string ===
 +
Converts variable into a string.  Can be useful in phrases or for defining class or id attributes for HTML elements
 +
{{codesample|<pre>
 +
<phrase ref="licenses_description_{license.as_string()}" />.
 +
</pre>}}
 +
 +
=== contains ===
 +
Returns a boolean depending whether the string contains a particular substring.
 +
{{codesample|<pre>
 +
<when test="title.contains('the')">
 +
</pre>}}
 +
 +
=== join ===
 +
Returns the concatentation of strings with a particular joining character.
 +
{{codesample|<pre>
 +
<when test="$list.join(':') = 'a:b:c'">
 +
  ...
 +
</when>
 +
</pre>}}
 +
 +
=== reverse ===
 +
Returns the reverse of a string (i.e. 'abc' becomes 'cba').
 +
{{codesample|<pre>
 +
<when test="type.reverse = 'tnetap'">
 +
</pre>}}
 +
 +
=== strlen ===
 +
Gets the integer length of a string.
 +
{{codesample|<pre>
 +
<when test="strlen(title) > 50">
 +
  ...
 +
</when>
 +
</pre>}}
 +
 +
=== substr ===
 +
Returns the substring of a string
 +
{{codesample|<pre>
 +
<when test="title.substr(0,3) = 'the'">
 +
</pre>}}
 +
 +
 +
== Integer Functions ==
 +
 +
=== add ===
 +
Returns the addition of one number to another.
 +
{{codesample|<pre>
 +
<when test="pages + 4 > 10">
 +
</pre>}}
 +
 +
=== divide ===
 +
Returns the division of one number by another.
 +
{{codesample|<pre>
 +
<when test="pages / 4 lt 10">
 +
</pre>}}
 +
 +
=== mod ===
 +
Returns the modulus (i.e. remainder) of a number from a base (e.g <tt>5 % 3</tt> equals 2.
 +
{{codesample|<pre>
 +
<when test="pages % 2 = 0">
 +
</pre>}}
 +
 +
=== multiply ===
 +
Returns the multiplication of one number by another.
 +
{{codesample|<pre>
 +
<when test="pages * 4 gt 10">
 +
</pre>}}
 +
 +
=== subtract ===
 +
Returns the substraction of one number from another.
 +
{{codesample|<pre>
 +
<when test="pages - 4 lt 10">
 +
</pre>}}
 +
 +
=== uminus ===
 +
Returns the negative value of an integer (e.g. 1 becomes -1).  This is a unary rather than binary operator like substract.
 +
{{codesample|<pre>
 +
<when test="-rating gt 5">
 +
</pre>}}
 +
 +
 +
== Date Functions ==
 +
 +
=== datemath ===
 +
Returns a date relative to the date provided, (e.g. two years ago).
 +
{{codesample|<pre>
 +
<when test="date lt today().datemath( -2,'year' )">
 +
</pre>}}
 +
 +
=== today ===
 +
Returns today's date
 +
{{codesample|<pre>
 +
<print expr="today()" />
 +
</pre>}}
  
−
{{codesample|
 
−
<pre>
 
−
<when test="is_set( creators )">
 
−
...
 
−
</when>
 
−
</pre>
 
−
}}
 
  
 
== List Functions ==
 
== List Functions ==
 +
 +
=== array_concat ===
 +
Concatenate multiple arrays into a single array
 +
 +
=== filter_compound_list ===
  
 
=== length ===
 
=== length ===
 +
Returns the number of items in the list.
 +
{{codesample|<pre>
 +
<if test="length(editors) gt 1">s</if>
 +
</pre>}}
 +
 +
=== one_of ===
 +
Returns a boolean depenbding on whether a variable is one of a number of values.
 +
{{codesample|<pre>
 +
<when test="type.one_of('article','conference_item','book')">
 +
</pre>}}
  
−
Returns the number of items in the list.
+
=== pretty_list ===
 +
 
 +
=== to_data_array ===
 +
 
 +
 
 +
== Data Object Functions ==
 +
 
 +
=== action_list ===
 +
Returns an array of actions for a particular data object.
 +
{{codesample|<pre>
 +
<foreach expr="action_list('eprint_summary_page_actions',$item)" iterator="action">
 +
</pre>}}
 +
 
 +
=== as_item ===
 +
Treats a variable as an item so other data object functions can be applied to it.
 +
{{codesample|<pre>
 +
  <when test="$doc.property('eprintid').as_item().property('type') = 'thesis'">
 +
</pre>}}
 +
 
 +
=== control_url ===
 +
Returns the control URL of a particular data object. (e.g. ''/cgi/users/home?screen=EPrint::View&eprintid=1234'')
 +
{{codesample|<pre>
 +
<a href="{$item.control_url()}">Download</a>
 +
</pre>}}
 +
 
 +
=== dataset ===
 +
Returns the string for the dataset of the data object.
 +
{{codesample|<pre>
 +
  <when test="$item.dataset() = 'document'">
 +
</pre>}}
 +
 
 +
=== main_item_property ===
 +
Get the property of parent data object.
 +
{{codesample|<pre>
 +
<print expr="$doc.main_item_property('note')" />
 +
</pre>}}
 +
 
 +
=== property ===
 +
Get the property of a data object
 +
{{codesample|<pre>
 +
<print expr="$item.property('note')">
 +
</pre>}}
 +
 
 +
=== related_objects ===
 +
Returns an array of objects related to the current data object through a particular property.
 +
{{codesample|<pre>
 +
<foreach expr="$doc.related_objects('http://eprints.org/relation/hasVersion')" iterator="rel">
 +
</pre>}}
 +
 
 +
=== 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.
 +
  &lt;print expr=&quot;compoundfield.subproperty( &apos;subfield2&apos; )&quot;/&gt;
 +
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.
 +
&lt;epc:print expr=&quot;userid.to_dataobj( &apos;user&apos;, &apos;userid&apos; ).property( &apos;username&apos; )&quot;/&gt;
 +
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/'')
 +
{{codesample|<pre>
 +
<a href="{$item.uri()}">Download</a>
 +
</pre>}}
 +
 
 +
=== url ===
 +
Returns the URL for a particular data object.
 +
{{codesample|<pre>
 +
<a href="{$doc.url()}">Download</a>
 +
</pre>}}
 +
 
 +
== EPrint Object Functions ==
 +
 
 +
=== contact_email ===
 +
Returns the contact email address for an EPrint object.  This will only return a contact email address if the <tt>email_for_doc_request</tt> function is set.
 +
{{codesample|<pre>
 +
<when test="$item.contact_email().is_set()">
 +
</pre>}}
 +
 
 +
=== documents ===
 +
Returns a list of all the documents for an EPrint object.
 +
{{codesample|<pre>
 +
<set name='docs' expr='$item.documents()'>
 +
</pre>}}
 +
 
 +
 
 +
== Document Object Functions ==
 +
 
 +
=== doc_size ===
 +
Returns the size of the document (i.e. in bytes).
 +
{{codesample|<pre>
 +
<print expr="$item.doc_size()" />
 +
</pre>}}
 +
 
 +
=== human_filesize ===
 +
Returns the human-readable file size.  Taking an integer number of bytes and converting into KB, MB, etc.  (E.g. <tt>258B</tt>, <tt>125KB</tt>, <tt>12MB</tt>).
 +
{{codesample|<pre>
 +
<epc:print expr="$item.doc_size().human_filesize()" />
 +
</pre>}}
 +
 
 +
=== is_public ===
 +
Returns a boolean for whether a document is publicly accessible.
 +
{{codesample|<pre>
 +
<when test="$doc.is_public()">
 +
</pre>}}
 +
 
 +
=== thumbnail_url ===
 +
Returns a URL string for a particular type of preview image for a document.
 +
{{codesample|<pre>
 +
<print expr="$doc.thumbnail_url('lightbox')" />
 +
</pre>}}
 +
 
 +
 
 +
== User Object Functions ==
 +
 
 +
=== has_role ===
 +
Returns a boolean for whether the user has a particular role.
 +
{{codesample|<pre>
 +
<when test="$current_user.has_role('ref/set_dates')">
 +
</pre>}}
 +
 
 +
 
 +
== Render Functions ==
 +
 
 +
=== action_button ===
 +
Returns an XHTML object for the button of a particular action on a data object.
 +
{{codesample|<pre>
 +
<print expr="$action.action_button()" />
 +
</pre>}}
 +
 
 +
=== action_icon ===
 +
Returns an XHTML object for the icon of a particular action on a data object.
 +
{{codesample|<pre>
 +
<print expr="$action.action_icon()" />
 +
</pre>}}
 +
 
 +
=== action_title ===
 +
Returns an XHTML object for the title of a particular action on a data object.
 +
{{codesample|<pre>
 +
<print expr="$action.action_title()" />
 +
</pre>}}
  
−
{{codesample|
+
=== citation ===
−
<pre>
+
Renders the XHTML citation for a data object with a specified style.  Encapsulated within a link to
−
<if test="length(editors) gt 1">s</if>
+
{{codesample|<pre>
−
</pre>
+
<print expr="$item.citation('default')" />
−
}}
+
</pre>}}
  
−
== String Functions ==
+
=== 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.
 +
{{codesample|<pre>
 +
<print expr="$item.citation_link('default')" />
 +
</pre>}}
  
−
=== one_of ===
+
=== 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.
 +
{{codesample|<pre>
 +
<print expr="creators.dumper" />
 +
</pre>}}
  
−
Returns true if the string is in the list of strings provided.
+
=== embed_video ===
 +
Renders an XHTML object to render an HTML5 video preview for a document that is a video or audio file.
 +
{{codesample|<pre>
 +
<print expr="$doc.embed_video" />
 +
</pre>}}
  
−
{{codesample|
+
=== icon ===
−
<pre>
+
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.
−
<when test="type.one_of( 'book','book_section' )">
+
{{codesample|<pre>
−
...
+
  <epc:print expr="$doc.icon('HoverPreview','noNewWindow','previewLeft')}" />
−
</when>
+
</pre>}}
−
</pre>
 
−
}}
 
  
−
=== reverse ===
+
=== phrase ===
 +
Returns an XHTML object for a phrase.
 +
{{codesample|<pre>
 +
<print expr="phrase('lib/document:preview')" />
 +
</pre>}}
  
−
Returns the reverse of a string (i.e. 'abc' becomes 'cba').
+
=== preview_link ===
 +
Returns an XHTML object containing an anchor (i.e. <tt><a href="..."></a></tt> 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.
 +
{{codesample|<pre>
 +
<print expr="$doc.preview_link($doc.citation_link('default'),'docs','lightbox')" />
 +
</pre>}}
  
−
{{codesample|
+
=== render_value_function ===
−
<pre>
+
Renders an XHTML object of the value of a field using a bespoke rendering functions
−
<when test="type.reverse = 'tnetap'">
+
{{codesample|<pre>
−
...
+
<print expr="$item.render_value_function('highlight_internal_authors', 'creators')" />
−
</when>
+
</pre>}}
−
</pre>
 
−
}}
 

Latest revision as of 01:42, 16 March 2022

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

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')">

related_objects

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')" />
Retrieved from ‘https://wiki.eprints.org/w/index.php?title=EPScript/Functions&oldid=15043’