Difference between revisions of "EPScript/Functions"

From EPrints Documentation
Jump to: navigation, search
(Added some more functions)
(Added all functions in EPrints::Script::Compiled)
Line 15: Line 15:
  
  
−
== Generic Functions ==
+
== Boolean Functions ==
  
 
=== is_set ===
 
=== is_set ===
Line 34: Line 34:
  
  
−
== List Functions ==
+
== 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>}}
  
−
=== length ===
+
=== contains ===
−
Returns the number of items in the list.
+
Returns a boolean depending whether the string contains a particular substring.
 
{{codesample|<pre>
 
{{codesample|<pre>
−
  <if test="length(editors) gt 1">s</if>
+
  <when test="title.contains('the')">
 
</pre>}}
 
</pre>}}
  
−
=== one_of ===
+
=== join ===
−
Returns a boolean depenbding on whether a variable is one of a number of values.
+
Returns the concatentation of strings with a particular joining character.
 
{{codesample|<pre>
 
{{codesample|<pre>
−
  <when test="type.one_of('article','conference_item','book')">
+
  <when test="$list.join(':') = 'a:b:c'">
 
   ...
 
   ...
 
  </when>
 
  </when>
 
</pre>}}
 
</pre>}}
−
 
−
 
−
== String Functions ==
 
  
 
=== reverse ===
 
=== reverse ===
Line 57: Line 60:
 
{{codesample|<pre>
 
{{codesample|<pre>
 
  <when test="type.reverse = 'tnetap'">
 
  <when test="type.reverse = 'tnetap'">
−
  ...
 
−
</when>
 
 
</pre>}}
 
</pre>}}
  
−
=== join ===
+
=== strlen ===
−
Returns the concatentation of strings with a particular joining character.
+
Gets the integer length of a string.
 
{{codesample|<pre>
 
{{codesample|<pre>
−
  <when test="$list.join(':') = 'a:b:c'">
+
  <when test="strlen(title) > 50">
 
   ...
 
   ...
 
  </when>
 
  </when>
Line 73: Line 74:
 
{{codesample|<pre>
 
{{codesample|<pre>
 
  <when test="title.substr(0,3) = 'the'">
 
  <when test="title.substr(0,3) = 'the'">
−
  ...
 
−
</when>
 
 
</pre>}}
 
</pre>}}
  
−
=== contains ===
+
 
−
Returns a boolean depending whether the string contains a particular substring.
+
== Integer Functions ==
 +
 
 +
=== add ===
 +
Returns the addition of one number to another.
 
{{codesample|<pre>
 
{{codesample|<pre>
−
  <when test="title.contains('the')">
+
  <when test="pages + 4 > 10">
−
  ...
 
−
</when>
 
 
</pre>}}
 
</pre>}}
  
−
=== as_string ===
+
=== divide ===
−
Converts variable into a string. Can be useful in phrases or for defining class or id attributes for HTML elements
+
Returns the division of one number by another.
 
{{codesample|<pre>
 
{{codesample|<pre>
−
  <phrase ref="licenses_description_{license.as_string()}" />.
+
  <when test="pages / 4 lt 10">
 
</pre>}}
 
</pre>}}
  
−
=== strlen ===
+
=== mod ===
−
Gets the integer length of a string.
+
Returns the modulus (i.e. remainder) of a number from a base (e.g <tt>5 % 3</tt> equals 2.
 
{{codesample|<pre>
 
{{codesample|<pre>
−
  <when test="strlen(title) > 50">
+
  <when test="pages % 2 = 0">
−
  ...
 
−
</when>
 
 
</pre>}}
 
</pre>}}
  
−
== Mathematical Functions ==
+
=== multiply ===
−
 
+
Returns the multiplication of one number by another.
−
=== add ===
 
−
Returns the addition of one number to another.
 
 
{{codesample|<pre>
 
{{codesample|<pre>
−
  <when test="pages + 4 > 10">
+
  <when test="pages * 4 gt 10">
−
  ...
 
−
</when>
 
 
</pre>}}
 
</pre>}}
  
Line 113: Line 107:
 
{{codesample|<pre>
 
{{codesample|<pre>
 
  <when test="pages - 4 lt 10">
 
  <when test="pages - 4 lt 10">
−
  ...
 
−
</when>
 
 
</pre>}}
 
</pre>}}
  
−
=== multiply ===
+
=== uminus ===
−
Returns the multiplication of one number by another.
+
Returns the negative value of an integer (e.g. 1 becomes -1).  This is a unary rather than binary operator like substract.
 
{{codesample|<pre>
 
{{codesample|<pre>
−
  <when test="pages * 4 gt 10">
+
  <when test="-rating gt 5">
−
  ...
 
−
</when>
 
 
</pre>}}
 
</pre>}}
  
−
=== divide ===
+
 
−
Returns the division of one number by another.
+
== Date Functions ==
 +
 
 +
=== datemath ===
 +
Returns a date relative to the date provided, (e.g. two years ago).
 
{{codesample|<pre>
 
{{codesample|<pre>
−
  <when test="pages / 4 lt 10">
+
  <when test="date lt today().datemath( -2,'year' )">
−
  ...
 
−
</when>
 
 
</pre>}}
 
</pre>}}
  
−
=== mod ===
+
=== today ===
−
Returns the modulus (i.e. remainder) of a number from a base (e.g <tt>5 % 3</tt> equals 2.
+
Returns today's date
 
{{codesample|<pre>
 
{{codesample|<pre>
−
  <when test="pages % 2 = 0">
+
  <print expr="today()" />
−
  ...
 
−
</when>
 
 
</pre>}}
 
</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">
 
−
  ...
 
−
</when>
 
−
</pre>}}
 
  
 +
== List Functions ==
 +
 +
=== array_concat ===
 +
Concatenate multiple arrays into a single array
  
−
== Rendering Functions ==
+
=== filter_compound_list ===
  
−
=== citation ===
+
=== length ===
−
Renders the XHTML citation for a data object with a specified style. Encapsulated within a link to
+
Returns the number of items in the list.
 
{{codesample|<pre>
 
{{codesample|<pre>
−
  <print expr="$item.citation('default')" />
+
  <if test="length(editors) gt 1">s</if>
 
</pre>}}
 
</pre>}}
  
−
=== citation_link ===
+
=== one_of ===
−
Renders the XHTML citation for a data object with a specified style, where the title is encompassed by a link to the data object.
+
Returns a boolean depenbding on whether a variable is one of a number of values.
 
{{codesample|<pre>
 
{{codesample|<pre>
−
  <print expr="$item.citation_link('default')" />
+
  <when test="type.one_of('article','conference_item','book')">
 
</pre>}}
 
</pre>}}
  
−
=== embed_video ===
+
=== pretty_list ===
−
Renders an XHTML object to render an HTML5 video preview for a document that is a video or audio file.
+
 
−
{{codesample|<pre>
+
=== to_data_array ===
−
<print expr="$doc.embed_video" />
 
−
</pre>}}
 
  
  
 
== Data Object Functions ==
 
== Data Object Functions ==
  
−
=== property ===
+
=== action_list ===
−
Get the property of a data object
+
Returns an array of actions for a particular data object.
 
{{codesample|<pre>
 
{{codesample|<pre>
−
  <print expr="$item.property('note')">
+
  <foreach expr="action_list('eprint_summary_page_actions',$item)" iterator="action">
 
</pre>}}
 
</pre>}}
  
−
=== main_item_property ===
+
=== as_item ===
−
Get the property of parent data object.
+
Treats a variable as an item so other data object functions can be applied to it.
 
{{codesample|<pre>
 
{{codesample|<pre>
−
<print expr="$doc.main_item_property('note')" />
+
  <when test="$doc.property('eprintid').as_item().property('type') = 'thesis'">
 
</pre>}}
 
</pre>}}
  
−
=== as_item ===
+
=== control_url ===
−
Treats a variable as an item so other data object functions can be applied to it.
+
Returns the control URL of a particular data object. (e.g. ''/cgi/users/home?screen=EPrint::View&eprintid=1234'')
 
{{codesample|<pre>
 
{{codesample|<pre>
−
  <when test="$doc.property('eprintid').as_item().property('type') = 'thesis'">
+
<a href="{$item.control_url()}">Download</a>
 
</pre>}}
 
</pre>}}
  
Line 195: Line 179:
 
{{codesample|<pre>
 
{{codesample|<pre>
 
   <when test="$item.dataset() = 'document'">
 
   <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>}}
 
</pre>}}
  
Line 201: Line 197:
 
{{codesample|<pre>
 
{{codesample|<pre>
 
  <foreach expr="$doc.related_objects('http://eprints.org/relation/hasVersion')" iterator="rel">
 
  <foreach expr="$doc.related_objects('http://eprints.org/relation/hasVersion')" iterator="rel">
 +
</pre>}}
 +
 +
=== 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>}}
 
</pre>}}
  
Line 210: Line 212:
  
  
−
== Date Functions ==
+
== 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>}}
 +
 
 +
=== citation ===
 +
Renders the XHTML citation for a data object with a specified style.  Encapsulated within a link to
 +
{{codesample|<pre>
 +
<print expr="$item.citation('default')" />
 +
</pre>}}
 +
 
 +
=== 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>}}
 +
 
 +
=== 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>}}
 +
 
 +
=== 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.
 +
{{codesample|<pre>
 +
  <epc:print expr="$doc.icon('HoverPreview','noNewWindow','previewLeft')}" />
 +
</pre>}}
 +
 
 +
=== phrase ===
 +
Returns an XHTML object for a phrase.
 +
{{codesample|<pre>
 +
<print expr="phrase('lib/document:preview')" />
 +
</pre>}}
  
−
=== today ===
+
=== preview_link ===
−
Returns today's date
+
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>
 
{{codesample|<pre>
−
  <print expr="today()" />
+
  <print expr="$doc.preview_link($doc.citation_link('default'),'docs','lightbox')" />
 
</pre>}}
 
</pre>}}
  
−
=== datemath ===
+
=== render_value_function ===
−
Returns a date relative to the date provided, (e.g. two years ago).
+
Renders an XHTML object of the value of a field using a bespoke rendering functions
 
{{codesample|<pre>
 
{{codesample|<pre>
−
  <when test="date lt today().datemath( -2,'year' )">
+
  <print expr="$item.render_value_function('highlight_internal_authors', 'creators')" />
 
</pre>}}
 
</pre>}}

Revision as of 01:39, 21 February 2022

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

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

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=14818’