Editing EPScript/Functions (section)

= Functions =

== Calling Functions ==
Functions can be called in two ways:
{{codesample|<pre>
 <when test="is_set( creators )">
</pre>}}
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.


== 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.
{{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>}}


== List Functions ==

=== array_concat ===
Concatenate multiple arrays into a single array

=== filter_compound_list ===

=== 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>}}

=== 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>}}

=== 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>}}

=== 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>}}

=== 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>}}

=== 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>}}

=== render_value_function ===
Renders an XHTML object of the value of a field using a bespoke rendering functions
{{codesample|<pre>
 <print expr="$item.render_value_function('highlight_internal_authors', 'creators')" />
</pre>}}