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