Difference between revisions of "EPScript"

From EPrints Documentation
Jump to: navigation, search
(Operators)
(Hash)
(16 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
{{formats}}
 
{{formats}}
 +
 +
'''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.
 
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 =
 
= Data Types =
Line 12: Line 52:
  
 
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:
 
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 test="type = 'patent'">
 
  ...   
 
  ...   
 
  </when>
 
  </when>
 +
</source>
  
 
=== Integers ===
 
=== 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.  
 
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.
 +
 +
If you need to test a boolean field, see the example at the end of this page.
  
 
== Data Objects ==
 
== 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:
 
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 test="usertype = 'editor'">
 
  ...
 
  ...
 
  </if>
 
  </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:
 
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.
  
<if test="$eprint.ispublished.one_of('unpub', 'submitted', 'inpress')"> (<print expr="$eprint.ispublished" />)</if>
+
== Hash ==
  
= Parameters =
+
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 dataobject, eg. $config{'base_url'}
  
$config{xxx} - a value from the configuration.
+
Note: To use the `$config`, you may need to wrap the whole expression in braces e.g.:
 +
<source lang="xml">
 +
  <component>
 +
    <field ref="a_set_or_named_set_field" options="{$config{default_value_for_field}}" required="yes" />
 +
  </component>
 +
</source>
  
$current_user - the current user, e.g., $current_user{username}
+
which would reference (in a cfg/cfg.d/example.pl file):
 +
<source lang="perl">
 +
$c->{default_value_for_field} = "amstrad";
 +
</source>
  
$current_lang - the id of the current language (such as 'en')
+
== XHTML ==
  
$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}'''
+
The citation method returns a pre-rendered value. You can't do anything with XHTML other than print it.
  
 
= Operators =
 
= Operators =
Line 50: Line 113:
  
 
Returns true if both the left-hand and the right-hand expressions return true.  
 
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 test="type = 'book' and is_set( creators )">
 
  ...
 
  ...
 
  </if>
 
  </if>
 +
</source>
  
 
===or===
 
===or===
 
Returns true if at least one of the expressions returns true.
 
Returns true if at least one of the expressions returns true.
 
+
<source lang="xml">
 
  <if test="type = 'book' or type = 'patent'">  
 
  <if test="type = 'book' or type = 'patent'">  
 
  ...
 
  ...
 
  </if>
 
  </if>
 +
</source>
  
 
===not===
 
===not===
 
Returns true if the expression is false and false if the expression is true.
 
Returns true if the expression is false and false if the expression is true.
 
+
<source lang="xml">
 
  <if test="!is_set( creators )">
 
  <if test="!is_set( creators )">
 
  ...
 
  ...
 
  </if>
 
  </if>
 +
</source>
  
 
==Comparison Operators==
 
==Comparison Operators==
Line 74: Line 140:
  
 
Returns true if the left-hand expression is less than the right-hand expression. This is only applicable to expressions that return numeric values.
 
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 test="length(editors) lt 6">
 
  ...
 
  ...
 
  </if>
 
  </if>
 +
</source>
  
 
===gt===
 
===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.
 
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 test="length(editors) gt 1">
 
  ...
 
  ...
 
  </if>
 
  </if>
 +
</source>
  
 
===equals===
 
===equals===
  
 
Returns true if the left-hand expression is equal to the right-hand expression. This applies to numeric, boolean, and string values.  
 
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 test="type = 'patent'">
 
  ...
 
  ...
 
  </if>
 
  </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".
 
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".
  
Line 100: Line 168:
  
 
The inverse of the equals operator, this returns true if the expressions are not equal.
 
The inverse of the equals operator, this returns true if the expressions are not equal.
 
+
<source lang="xml">
 
  <if test="type != 'book'">
 
  <if test="type != 'book'">
 
  ...
 
  ...
 
  </if>
 
  </if>
 +
</source>
  
 
= Functions =
 
= Functions =
Line 110: Line 179:
  
 
Functions can be called in two ways:
 
Functions can be called in two ways:
 
+
<source lang="xml">
 
  <when test="is_set( creators )">
 
  <when test="is_set( creators )">
 
+
</source>
 +
<source lang="xml">
 +
<print expr="citation( eprint,title )">
 +
</source>
 
or
 
or
 
+
<source lang="xml">
<when test="creators.is_set">
+
<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.
 
These are interchangable, but it may be beneficial to use a specific form in some cases.
  
== Generic Functions ==
+
== Function List ==
  
 
=== is_set ===
 
=== is_set ===
Line 126: Line 201:
 
* 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.
 
+
<source lang="xml">
 
  <when test="is_set( creators )">
 
  <when test="is_set( creators )">
 
  ...
 
  ...
 
  </when>
 
  </when>
 +
</source>
 +
parameters: is_set(ANYTHING)
  
== List Functions ==
+
returns: BOOLEAN
  
 
=== length ===
 
=== length ===
  
 
Returns the number of items in the list.
 
Returns the number of items in the list.
 
+
<source lang="xml">
 
  <if test="length(editors) gt 1">s</if>
 
  <if test="length(editors) gt 1">s</if>
 +
</source>
 +
parameters: length(ANYTHING) .. although only Field Values make much sense
  
== String Functions ==
+
returns: INTEGER
  
 
=== one_of ===
 
=== one_of ===
  
 
Returns true if the string is in the list of strings provided.
 
Returns true if the string is in the list of strings provided.
 
+
<source lang="xml">
 
  <when test="type.one_of( 'book','book_section' )">
 
  <when test="type.one_of( 'book','book_section' )">
 
  ...
 
  ...
 
  </when>
 
  </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 ===
 
=== reverse ===
  
 
Returns the reverse of a string (i.e. 'abc' becomes 'cba').
 
Returns the reverse of a string (i.e. 'abc' becomes 'cba').
 
+
<source lang="xml">
 
  <when test="type.reverse = 'tnetap'">
 
  <when test="type.reverse = 'tnetap'">
 
  ...
 
  ...
 
  </when>
 
  </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 =
 
= Examples =
  
 
== Pluralising the editors of a book ==
 
== Pluralising the editors of a book ==
 
+
<source lang="xml">
 
  <if test="type = 'book' and is_set(editors)">
 
  <if test="type = 'book' and is_set(editors)">
 
   <print expr="editors" />, (ed<if test="length(editors) gt 1">s</if>
 
   <print expr="editors" />, (ed<if test="length(editors) gt 1">s</if>
 
  </if>
 
  </if>
 
+
</source>
 
== Rendering the URL of an EPrint ==
 
== Rendering the URL of an EPrint ==
 
+
<source lang="xml">
 
  <print expr="$config{base_url}" />/<print expr="eprintid" />/
 
  <print expr="$config{base_url}" />/<print expr="eprintid" />/
 +
</source>
 +
== Testing a boolean field ==
 +
Boolean fields can be TRUE, FALSE or NULL. Just doing a test="boolean_field" isn't enough. Use this:
 +
<source lang="xml">
 +
<if test="boolean_field = 'TRUE'">
 +
  ...
 +
</if>
 +
</source>

Revision as of 15:25, 11 June 2018

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)

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

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.

If you need to test a boolean field, see the example at the end of this page.

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'">
 ...
 </if>

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 dataobject, eg. $config{'base_url'}

Note: To use the `$config`, you may need to wrap the whole expression in braces e.g.:

  <component>
    <field ref="a_set_or_named_set_field" options="{$config{default_value_for_field}}" required="yes" />
  </component>

which would reference (in a cfg/cfg.d/example.pl file):

$c->{default_value_for_field} = "amstrad";

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.

 <if test="type = 'book' and is_set( creators )">
 ...
 </if>

or

Returns true if at least one of the expressions returns true.

 <if test="type = 'book' or type = 'patent'"> 
 ...
 </if>

not

Returns true if the expression is false and false if the expression is true.

 <if test="!is_set( creators )">
 ...
 </if>

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.

 <if test="length(editors) lt 6">
 ...
 </if>

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.

 <if test="length(editors) gt 1">
 ...
 </if>

equals

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>

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'">
 ...
 </if>

Functions

Calling Functions

Functions can be called in two ways:

 <when test="is_set( creators )">
 <print expr="citation( eprint,title )">

or

 <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 )">
 ...
 </when>

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

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'">
 ...
 </when>

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()

returns: DATAOBJECT

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>
 </if>

Rendering the URL of an EPrint

 <print expr="$config{base_url}" />/<print expr="eprintid" />/

Testing a boolean field

Boolean fields can be TRUE, FALSE or NULL. Just doing a test="boolean_field" isn't enough. Use this:

 <if test="boolean_field = 'TRUE'">
   ...
 </if>