Difference between revisions of "EPScript"

From EPrints Documentation
Jump to: navigation, search
(Redirected page to EPScript/Introduction)
(Tag: New redirect)
 
(8 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{formats}}
+
#REDIRECT [[EPScript/Introduction]]
 
 
'''NOTE:''' There are many functions not documented on this page. Look in  ~/perl_lib/EPrints/Script/Compiled.pm for other functions.
 
 
 
This is an introduction.
 
 
 
= Language Synopsis =
 
 
 
$var{xxx} - get the value of 'xxx' in $var
 
 
 
$var{xxx}{yyy} - get the value of 'yyy' in 'xxx' in $var
 
 
 
$var.xxx(yyy) - call method 'xxx' on $var with argument 'yyy'
 
 
 
xxx(yyy) - call method 'xxx' with argument 'yyy'
 
 
 
xxx - get the value of field 'xxx'
 
 
 
xxx OP yyy - test whether 'xxx' is OP 'yyy' (=, !=, etc.)
 
 
 
xxx LOGIC yyy - test whether 'xxx' LOGIC 'yyy' (and, or, not etc.)
 
 
 
== Examples ==
 
 
 
$config{oai}{v2}{archive_id} - gets the current OAI repository identifier
 
 
 
$current_user{department}.is_set() - returns true if the user's department field is set
 
 
 
published.one_of('submitted','published') - returns true if published is 'unpub' or 'published'
 
 
 
$item{type} = 'patent' - returns true if type from item is 'patent'
 
 
 
join($item{userid}.as_item(){collection},',') - useful for extracting data in 'multiple' fields. For the owner of the eprint, return all 'collection's as a comma-separated string. See [[How to control eprint workflow based on a user field]]
 
 
 
= Global Variables =
 
 
 
$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:
 
<source lang="xml">
 
<when test="type = 'patent'">
 
... 
 
</when>
 
</source>
 
 
 
=== 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:
 
<source lang="xml">
 
<if test="usertype = 'editor'">
 
...
 
</if>
 
</source>
 
 
 
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:
 
<source lang="xml">
 
<if test="$eprint{ispublished}.one_of('unpub', 'submitted', 'inpress')"> (<print expr="$eprint{ispublished}" />)</if>
 
</source>
 
 
 
== 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==
 
 
 
===and===
 
 
 
Returns true if both the left-hand and the right-hand expressions return true.
 
<source lang="xml">
 
<if test="type = 'book' and is_set( creators )">
 
...
 
</if>
 
</source>
 
 
 
===or===
 
Returns true if at least one of the expressions returns true.
 
<source lang="xml">
 
<if test="type = 'book' or type = 'patent'">
 
...
 
</if>
 
</source>
 
 
 
===not===
 
Returns true if the expression is false and false if the expression is true.
 
<source lang="xml">
 
<if test="!is_set( creators )">
 
...
 
</if>
 
</source>
 
 
 
==Comparison Operators==
 
 
 
===lt===
 
 
 
Returns true if the left-hand expression is less than the right-hand expression. This is only applicable to expressions that return numeric values.
 
<source lang="xml">
 
<if test="length(editors) lt 6">
 
...
 
</if>
 
</source>
 
 
 
===gt===
 
 
 
Returns true if the left-hand expression is greater than the right-hand expression. This is only applicable to expressions that return numeric values.
 
<source lang="xml">
 
<if test="length(editors) gt 1">
 
...
 
</if>
 
</source>
 
 
 
===equals===
 
 
 
Returns true if the left-hand expression is equal to the right-hand expression. This applies to numeric, boolean, and string values.
 
<source lang="xml">
 
<if test="type = 'patent'">
 
...
 
</if>
 
</source>
 
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.
 
<source lang="xml">
 
<if test="type != 'book'">
 
...
 
</if>
 
</source>
 
 
 
= Functions =
 
 
 
== Calling Functions ==
 
 
 
Functions can be called in two ways:
 
<source lang="xml">
 
<when test="is_set( creators )">
 
</source>
 
<source lang="xml">
 
<print expr="citation( eprint,title )">
 
</source>
 
or
 
<source lang="xml">
 
<when test="creators.is_set()">
 
</source>
 
<source lang="xml">
 
<print expr="eprint.citation( title )">
 
</source>
 
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.
 
<source lang="xml">
 
<when test="is_set( creators )">
 
...
 
</when>
 
</source>
 
parameters: is_set(ANYTHING)
 
 
 
returns: BOOLEAN
 
 
 
=== length ===
 
 
 
Returns the number of items in the list.
 
<source lang="xml">
 
<if test="length(editors) gt 1">s</if>
 
</source>
 
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.
 
<source lang="xml">
 
<when test="type.one_of( 'book','book_section' )">
 
...
 
</when>
 
</source>
 
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').
 
<source lang="xml">
 
<when test="type.reverse = 'tnetap'">
 
...
 
</when>
 
</source>
 
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.
 
<source lang="xml">
 
<epc:print expr="$item.citation('default')" />
 
</source>
 
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.
 
<source lang="xml">
 
  <epc:print expr="$item{userid}.as_item(){username}" />
 
</source>
 
parameters: FIELDVALUE.as_item()
 
 
 
returns: DATAOBJECT
 
 
 
= Examples =
 
 
 
== Pluralising the editors of a book ==
 
<source lang="xml">
 
<if test="type = 'book' and is_set(editors)">
 
  <print expr="editors" />, (ed<if test="length(editors) gt 1">s</if>
 
</if>
 
</source>
 
== Rendering the URL of an EPrint ==
 
<source lang="xml">
 
<print expr="$config{base_url}" />/<print expr="eprintid" />/
 
</source>
 

Latest revision as of 02:21, 21 February 2022