Difference between revisions of "EPScript"

From EPrints Documentation
Jump to: navigation, search
(Calling Functions)
(Redirected page to EPScript/Introduction)
(Tag: New redirect)
(11 intermediate revisions by 5 users not shown)
Line 1: Line 1:
#REDIRECT [[EPScript/Introduction]]
This is an introduction.
= Parameters =
$config{xxx} - a value from the configuration.
$current_user - the current user, e.g., $current_user{username}
$current_lang - the id of the current language (such as 'en')
$item - the current item (usually an eprint, but not always, e.g., in citations or workflows for user objects), e.g., $item{eprintid}. If you just use '''eprintid''' it is a shortcut for '''$item{eprintid}'''
= Data Types =
EPScript allows for two primitive data types (string and integer) as well as providing the means to access properties of data objects such as EPrints or Users.
== Primitive Types ==
=== Strings and characters ===
These are contained within either double quotes ("") or single quotes (<nowiki>''</nowiki>). There is no difference between the two, but it may be easier to use one sort when inside an XML attribute. For example:
<when test="type = 'patent'">
=== Integers ===
Integers are defined as a string of numbers from 0-9, e.g. 300. Leading zeros do not have any effect, and decimal values are currently not supported.
=== Booleans ===
True or false values. Returned by = gt and lt and oneof and used in <if> etc.
== Data Objects ==
Data Objects include most of the key EPrints objects - whether an EPrint itself, documents related to the EPrint, or a user. EPScript treats all of these data objects the same, with a simple approach to retrieve properties. When an EPScript is executed, an 'item' object is supplied. In the case of a citation file, this will be the item for which the citation is being created. For a workflow, this will be the object on which the workflow acts (e.g. an EPrint or a user). Properties of main objects can be accessed using a shortened approach - the following example is from a user workflow, so the usertype property is available:
<if test="usertype = 'editor'">
There are cases, however, where two or more data objects may be provided - such as an EPrint and a user. Here the main item can still be accessed in the short form, but other objects use a dollar notation. In this example, the EPrint is available as $eprint:
<if test="$eprint{ispublished}.one_of('unpub', 'submitted', 'inpress')"> (<print expr="$eprint{ispublished}" />)</if>
== Field Values ==
Values associated with a data object field. The field which the value belongs to can effect how it is rendered, and compared to other values.
== Hash ==
This currently only used by the $config parameter to give access to configuration options. Get values out of it the same way you get values from a dataobejct, eg. $config{'base_url'}
== XHTML ==
The citation method returns a pre-rendered value. You can't do anything with XHTML other than print it.
= Operators =
==Logical Operators==
Returns true if both the left-hand and the right-hand expressions return true.
<if test="type = 'book' and is_set( creators )">
Returns true if at least one of the expressions returns true.
<if test="type = 'book' or type = 'patent'">
Returns true if the expression is false and false if the expression is true.
<if test="!is_set( creators )">
==Comparison Operators==
Returns true if the left-hand expression is less than the right-hand expression. This is only applicable to expressions that return numeric values.
<if test="length(editors) lt 6">
Returns true if the left-hand expression is greater than the right-hand expression. This is only applicable to expressions that return numeric values.
<if test="length(editors) gt 1">
Returns true if the left-hand expression is equal to the right-hand expression. This applies to numeric, boolean, and string values.
<if test="type = 'patent'">
If the left OR the right value is a FIELDVALUE of a multiple field, then it returns true if the other value matches any of the values on the other side. eg. "subjects = 'group_foo'" will be true if any of the subjects are "group_foo".
===not equals===
The inverse of the equals operator, this returns true if the expressions are not equal.
<if test="type != 'book'">
= Functions =
== Calling Functions ==
Functions can be called in two ways:
<when test="is_set( creators )">
<print expr="citation( eprint,title )">
<when test="creators.is_set()">
<print expr="eprint.citation( title )">
These are interchangable, but it may be beneficial to use a specific form in some cases.
== Function List ==
=== 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 )">
parameters: is_set(ANYTHING)
returns: BOOLEAN
=== length ===
Returns the number of items in the list.
<if test="length(editors) gt 1">s</if>
parameters: length(ANYTHING) .. although only Field Values make much sense
returns: INTEGER
=== one_of ===
Returns true if the string is in the list of strings provided.
<when test="type.one_of( 'book','book_section' )">
Can in theory use any type of value. Will use the "=" method to compare them.
parameters: ANYTHING.one_of( LIST )
returns: BOOLEAN
=== reverse ===
Returns the reverse of a string (i.e. 'abc' becomes 'cba').
<when test="type.reverse = 'tnetap'">
This function was largely used for debugging, it's not very useful...
parameters: reverse(STRING)
returns: STRING
=== yesno ===
Returns a string "yes" or "no" depending on the value of the boolean passed to it.
parameters: yesno(BOOLEAN)
returns: STRING
=== citation ===
Can only be called on a dataobject. eg. $item or $current_user. It returns the object rendered using the specified citation style.
<epc:print expr="$item.citation('default')" />
The results of citation are only really useful for rendering, not testing.
parameters: DATAOBJ.citation(STRING)
returns: XHTML data
=== as_item ===
A very useful little method. This can only be called on a field value of a field of type "itemref". It returns the item itself.
  <epc:print expr="$item{userid}.as_item(){username}" />
parameters: FIELDVALUE.as_item()
= Examples =
== Pluralising the editors of a book ==
<if test="type = 'book' and is_set(editors)">
  <print expr="editors" />, (ed<if test="length(editors) gt 1">s</if>
== Rendering the URL of an EPrint ==
<print expr="$config{base_url}" />/<print expr="eprintid" />/

Latest revision as of 02:21, 21 February 2022