Difference between revisions of "EPScript/Data Types"

From EPrints Documentation
Jump to: navigation, search
m (not)
(Added some more types + formats template)
 
(24 intermediate revisions by 3 users not shown)
Line 1: Line 1:
=EPScript=
+
{{formats}}
  
{{devel}}
+
{{EPScript}}
  
==Data Types==
+
= Data Types =
 +
EPScript has various data types, both primitive (strings, integers and booleans) and [[Data Objects]] for the various concepts that can be represented within an EPrints repository.
 +
 +
== Primitive Types ==
  
===Strings and characters===  
+
=== Strings ===  
 +
'''STRING''' is 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:
+
{{codesample|<pre>
 +
<when test="type = 'patent'">
 +
  ...
 +
</when>
 +
</pre>}}
  
{{codesample|
+
=== Integers ===
<pre>
+
'''INTEGER''' is defined as a string of numbers from 0-9, (e.g. <tt>300</tt>). Leading zeros do not have any effect, and decimal values are currently not supported.
<when test="type = 'patent'">
 
...
 
</when>
 
</pre>
 
}}
 
  
===Integers===
+
=== Booleans ===
 +
'''BOOLEAN''' is either true or false.
  
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.
+
=== Dates ===
 +
'''DATE''' is defined as a string that conforms to the ISO date format (e.g. <tt>2022-02-20</tt>),
  
 +
== 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, a 'main' 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:
  
 +
{{codesample|<pre>
 +
<if test="usertype = 'editor'">
 +
  ...
 +
</if>
 +
</pre>}}
  
==Logical Operators==
+
There are cases, however, where two or more data objects may be provided - such as an EPrint and a user. Here the main object can still be accessed in the short form, but other objects use a dollar notation. In this example, the EPrint is available as $eprint:
  
===and===
+
{{codesample|<pre>
 +
<if test="$eprint.ispublished.one_of('unpub', 'submitted', 'inpress')"> (<print expr="$eprint.ispublished" />)</if>
 +
</pre>}}
  
Returns true if both the left-hand and the right-hand expressions return true.  
+
== 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.
  
{{codesample|
+
== Hashes ==
<pre>
+
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'}
<if test="type = 'book' and is_set( creators )">
 
...
 
</if>
 
</pre>
 
}}
 
  
===or===
+
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>
  
Returns true if at least one of the expressions returns true.
+
which would reference (in a cfg/cfg.d/example.pl file):
 +
<source lang="perl">
 +
$c->{default_value_for_field} = "amstrad";
 +
</source>
  
{{codesample|
+
== XHTML ==
<pre>
+
The citation method returns a pre-rendered value. You can't do anything with XHTML other than print it.
<if test="type = 'book' or type = 'patent'">
 
...
 
</if>
 
</pre>
 
}}
 
 
 
===not===
 
 
 
Returns true if the expression is false and false if the expression is true.
 
 
 
{{codesample|
 
<pre>
 
<if test='!is_set( creators )'">
 
...
 
</if>
 
</pre>
 
}}
 
 
 
==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.
 
 
 
{{codesample|
 
<pre>
 
<if test="length(editors) lt 6">
 
...
 
</if>
 
</pre>
 
}}
 
 
 
===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.
 
 
 
{{codesample|
 
<pre>
 
<if test="length(editors) gt 1">
 
...
 
</if>
 
</pre>
 
}}
 
 
 
===equals===
 
 
 
Returns true if the left-hand expression is equal to the right-hand expression. This applies to numeric, boolean, and string values.
 
 
 
{{codesample|
 
<pre>
 
<if test="type = 'patent'">
 
...
 
</if>
 
</pre>
 
}}
 
 
 
===not equals===
 
 
 
The inverse of the equals operator, this returns true if the expressions are not equal.
 
 
 
{{codesample|
 
<pre>
 
<if test="type != 'book'">
 
...
 
</if>
 
</pre>
 
}}
 
 
 
==Control Structures==
 
 
 
===if===
 
 
 
Inserts the content of the <if> element if the EPScript in the test attribute returns true.
 
 
 
{{codesample|
 
<pre>
 
<if test="date_effective">(<print expr="date_effective" opts="res=year" />)</if>
 
</pre>
 
}}
 
 
 
===choose/when/otherwise===
 
 
 
A <choose> element consists of one or many <when> elements and an optional <otherwise> element. The test attribute of each <when> element is evaluated, and if this returns true the content is included and execution leaves the <choose> structure. If <i>no</i> test attribute returns true and an <otherwise> element is provided, the content of the <otherwise> element is included.
 
 
 
{{codesample|
 
<pre>
 
<choose>
 
  <when test="title"><print expr="title" /></ep:when>
 
  <otherwise><print expr="type" /> #<print expr="eprintid" /></otherwise>
 
</choose>
 
</pre>
 
}}
 
 
 
==Procedures==
 
 
 
===print===
 
 
 
Outputs the result of the provided expression attribute as a string. If the result is boolean, TRUE or FALSE will be produced.
 
 
 
{{codesample|
 
<pre>
 
<print expr="isbn" />
 
</pre>
 
}}
 
 
 
===phrase===
 
 
 
Outputs the phrase given in the ref attribute. To provide values for pins in the phrases, the param element is used, with the name attribute giving the pin name and the element content the value to pass.
 
 
 
{{codesample|
 
<pre>
 
<phrase ref="my_phrase"><param name="my_pin">Pin Value</param></phrase>
 
</pre>
 
}}
 

Latest revision as of 02:20, 21 February 2022

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)


EPScript

Data Types

EPScript has various data types, both primitive (strings, integers and booleans) and Data Objects for the various concepts that can be represented within an EPrints repository.

Primitive Types

Strings

STRING is 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

INTEGER is 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

BOOLEAN is either true or false.

Dates

DATE is defined as a string that conforms to the ISO date format (e.g. 2022-02-20),

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, a 'main' 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 object 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.

Hashes

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.