scripting eprints. light on syntax object->function(arg1, arg2) incomplete designed to give...
TRANSCRIPT
![Page 1: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/1.jpg)
Scripting EPrints
![Page 2: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/2.jpg)
Light on syntax object->function(arg1, arg2)
Incomplete Designed to
give you a feel for the EPrints data model introduce you to the most significant
objects how they relate to one another their most common methods
act as a jumping off point for exploring
About This Talk
![Page 3: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/3.jpg)
EPrints modules have embedded documentation
Extract it using perldoc perldoc perl_lib/EPrints/EPrint.pm
Finding Documentation
![Page 4: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/4.jpg)
EPrints 3.0
This talk based on EPrints 2.3 series 3.0 API still being finalised
tidies up object hierarchy resolves some of 2.3’s naming clashes
lots of extra functionality but core data model remains the same
EPrints 3.0 is fully back-compatible 2.3 scripts will work with EPrints 3.0
![Page 5: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/5.jpg)
1. Data EPrints, Users, Documents, Subjects,
Subscriptions
2. Data collections DataSets, MetaFields
3. Searching your data SearchExpressions
4. Scripting your archive Archives, Session
Roadmap
![Page 6: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/6.jpg)
EPrints, Users, Documents, Subjects, Subscriptions
1. Data
![Page 7: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/7.jpg)
Data Model Sketch
EPrint
![Page 8: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/8.jpg)
Data Model Sketch
EPrint
Document
Document
HTMLHTML
HTML
all documents
![Page 9: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/9.jpg)
Data Model Sketch
EPrint
Document
Document
User
HTMLHTML
HTML
owner
all documents
![Page 10: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/10.jpg)
Data Model Sketch
EPrint
Document
Document
User
HTMLHTML
HTML
owner
owned eprints
all documents
EPrint
![Page 11: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/11.jpg)
Data Model Sketch
EPrint
Document
Document
User
Subscription Subscription
HTMLHTML
HTML
owner
owned eprints
all documents
subscriptions
EPrint
![Page 12: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/12.jpg)
Data Model Sketch
EPrint
Document
Document
User
Subscription Subscription
HTMLHTML
HTML
Subject
owner
owned eprints
all documents
subscriptions
EPrint
![Page 13: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/13.jpg)
Data Model Sketch
EPrint
Document
Document
User
Subscription Subscription
HTMLHTML
HTML
Subject
Subject
Subject
parent
child
owner
owned eprints
all documents
subscriptions
EPrint
![Page 14: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/14.jpg)
Data Model Sketch
EPrint
Document
Document
User
Subscription Subscription
HTMLHTML
HTML
Subject
Subject
Subject
parent
child
owner
owned eprints
all documents
posted eprints
subscriptions
EPrint
EPrint
![Page 15: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/15.jpg)
An EPrint object represents a single deposit in your EPrints archive
has some metadata fields has one or more documents is owned by a user
EPrint
![Page 16: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/16.jpg)
new(session, id) create an EPrint object for an existing
deposit create(session, dataset, data)
create a new EPrint object
More on sessions and datasets later!
Creating EPrints
![Page 17: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/17.jpg)
EPrint is a subclass of DataObj DataObj provides common methods
for accessing metadata rendering XHTML output
Introducing DataObj
![Page 18: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/18.jpg)
Inherited from DataObj
get_id get_url(staff)
get the URL of an EPrint e.g. URL to the abstract page of an eprint in
the archive if staff is true then returns the URL to the
staff view, which shows more detail get_type()
get the EPrint type e.g. article, book, thesis, conference
paper...
![Page 19: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/19.jpg)
get_value(fieldname) get the value of the named field
set_value(fieldname, value) set the value of the named field Remember to call commit() to make
changes in database! is_set(fieldname)
true if the named field has a value
Inherited from DataObj
![Page 20: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/20.jpg)
remove() erase the eprint and any associated
records/files from the database and filesystem
this should only be called on EPrints in the "inbox" or "buffer" datasets
commit() commit any changes made to the
database datestamp()
set the last modified date to today
EPrint Methods
![Page 21: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/21.jpg)
move_to_deletion() transfer the eprint to the deletion dataset should only be called on eprints in the
archive dataset
See also: move_to_inbox() move_to_buffer() move_to_archive()
Moving EPrints Around
![Page 22: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/22.jpg)
generate_static() generate the static abstract page for the
eprint in a multi-language archive this will
generate a page in each language
Rendering EPrints
![Page 23: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/23.jpg)
render_citation(style) create an XHTML citation for the EPrint if style is set then use the named citation
style defined in citations-en.xml
render_citation_link(style) as above, but citation is linked to the
EPrint’s abstract page
Rendering - Inherited from DataObj
![Page 24: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/24.jpg)
render_value(fieldname, showall)
get an XHTML fragment containing the rendered version of the value of the named field
in the current language if showall is true then all languages are
rendered usually used for staff viewing (checking) data
Rendering - Inherited from DataObj
![Page 25: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/25.jpg)
Rendering Tips
Most rendering methods return XHTML
but not a string! XML Node objects
DocumentFragment, Element, TextNode...
In your scripts, build a document tree from these nodes
e.g. node1->appendChild(node2) then flatten it to a string Why? It’s easier to manipulate a tree
than to manipulate a large string
![Page 26: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/26.jpg)
XML Node objects are not part of EPrints
XML::DOM or XML::GDOME libraries explore these libraries using perldoc
XHTML is good for building Web pages
but not so good for command line output!
use tree_to_utf8() extracts a string from the result of any
rendering method tree_to_utf8( eprint->render_citation)
More Rendering Tips
![Page 27: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/27.jpg)
get_user() get a User object representing the user
to whom the EPrint belongs get_all_documents()
get a list of all the Document objects associated with the EPrint
We will look at these objects next...
Navigating to Related Objects
![Page 28: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/28.jpg)
User
A User object represents a single registered user
Also a subclass of DataObj inherits metadata access methods
get_url get_type get_value set_value is_set
inherits rendering methods render_citation render_citation_link render_value
Also has commit and remove inherited from DataObj in 3.0
![Page 29: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/29.jpg)
new(session, id) create a User object from an existing
user record user_with_email(session, email) user_with_username(session, username)
create_user(session, access_level)
create a new User
Creating Users
![Page 30: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/30.jpg)
User Accessors
get_editable_eprints() get a list of EPrints that the user can edit
get_owned_eprints(dataset) get a list of EPrints owned by the user in
the dataset is_owner(eprint)
true if the user is the owner of the EPrint get_subscriptions()
get a list of Subscriptions associated with the user
![Page 31: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/31.jpg)
A single document associated with an eprint
may actually contain one or more physical files
PDF = 1 file HTML + images = many files
Another subclass of DataObj
Document
![Page 32: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/32.jpg)
new(session, docid) create a Document object from an
existing record create(session, eprint)
create a new Document object for the given EPrint
Creating a Document Object
![Page 33: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/33.jpg)
get_eprint() get the EPrint object the document is
associated with local_path()
get the full path of the directory where the document is stored in the filesystem
files() get a list of (filename, file size) pairs
Document Accessors
![Page 34: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/34.jpg)
get_main() set_main(main_file)
get/set the ‘main’ file for the document e.g. if the document is multipage HTML with
images, the main file needs to be set to the top index.html file
when rendering document links, EPrints always links to the main file in the document
set_format(format) sets the document format
Main File and Format
![Page 35: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/35.jpg)
Adding Files to Documents
upload(filehandle, filename) uploads the contents of the given file
handle adds the file to the document (using the
given filename) add_file(file, filename)
adds a file to the document (using the given filename)
file is the full path to the file
![Page 36: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/36.jpg)
upload_url(url) grab file(s) from given URL in the case of HTML, only relative links
will be followed add_archive(file, format)
add files from a .zip or .tar.gz archive remove_file(filename)
remove the named file from the Document
Adding Files to Documents
![Page 37: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/37.jpg)
A single subject from the subject hierarchy
Another subclass of DataObj
Subject
![Page 38: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/38.jpg)
new(session, subjectid) create a Subject object from an existing
subject create(session, id, name, parent, depositable)
create a new Subject depositable specifies whether or not
users can deposit eprints in the subject
Creating Subjects
![Page 39: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/39.jpg)
children() get a list of Subjects which are the
children of the subject get_parents()
get a list of Subjects which are the parents of the subject
subject_label(session, subject_tag)
get the full label of a subject, including parents
Subject Accessors
![Page 40: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/40.jpg)
count_eprints(dataset) get the number of eprints associated
with the subject posted_eprints(dataset)
get a list of EPrints associated with the subject
Subject Accessors
![Page 41: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/41.jpg)
render_with_path(session, topsubjid)
get a DocumentFragment containing the subject path
example of a subject path:H Social Sciences > HD Industries. Land use.
Labor > HD28 Management. Industrial Management
Rendering Subjects
![Page 42: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/42.jpg)
A stored search which is performed every day/week/month on behalf of a user
get_user() get the User who owns the subscription
Another subclass of DataObj
Subscription
![Page 43: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/43.jpg)
new(session, id) create a Subscription object from an
existing subscription create(session, userid)
create a new Subscription object for the given user
Creating Subscriptions
![Page 44: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/44.jpg)
send_out_subscription() search for new items matching the
subscription settings email them to the user owning the
subscription
Processing Subscriptions
![Page 45: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/45.jpg)
DataObj Hierarchy
![Page 46: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/46.jpg)
So Far..
We’ve looked at individual data objects
but an EPrints archive holds many eprints and documents, has many registered users etc.
how do we access them collectively? We’ve seen the get_value and set_value methods for metadata
but an archive’s metadata is configurable so how do we know what metadata fields
an EPrint, User etc. has? how do we access properties of the fields?
![Page 47: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/47.jpg)
DataSets and MetaFields
2. Data Collections
![Page 48: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/48.jpg)
A collection of data items Tells us all the possible types in the
collection e.g. EPrints may be article, thesis
Tells us the fields in each type e.g. article has title, authors, publication... e.g. conference_item has title, authors,
event_title, event_date..
Can also tell us all the fields that apply to a dataset
title, authors, publication, event_title..
Dataset
![Page 49: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/49.jpg)
ArchiveMetadataFieldsConfig.pm fields in each dataset additional system fields defined in
EPrint.pm, User.pm etc.
metadata-types.xml types in each dataset fields that apply to each type
Dataset Configuration
![Page 50: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/50.jpg)
Datasets in EPrints
archive EPrints that are live in the main archive
buffer EPrints that have been submitted for editorial
approval deletion
EPrints that have been deleted from the archive inbox
EPrints which users are still working on eprint
All EPrints from archive, buffer, deletion and inbox
![Page 51: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/51.jpg)
user all registered Users
subject all Subjects in the subject tree
document the Documents belonging to all EPrints
in the archive subscription
the Subscriptions which Users have requested
Datasets in EPrints
![Page 52: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/52.jpg)
id() get the id of the dataset
count(session) get the number of items in the dataset
get_item_ids(session) get a list of ids of the items in the
dataset
DataSet Accessors
![Page 53: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/53.jpg)
Datasets and MetaFields
Many Dataset methods return MetaField objects
A MetaField is a single field in a dataset tells us properties of the field
e.g. name, type, input_rows, maxlength, multiple etc.
configured in ArchiveMetadataFieldsConfig.pm but not the field value
the value is specific to the individual EPrint, User etc.
e.g. eprint->get_value(“title”)
![Page 54: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/54.jpg)
get_name() get the field name
get_type() get the field type
get_property(name) set_property(name, value)
get/set the named property to the given value
MetaField Methods
![Page 55: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/55.jpg)
MetaField Type Hierarchy
![Page 56: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/56.jpg)
has_field(fieldname) true if the dataset has a field of that
name get_field(fieldname)
get a MetaField object describing the named field
DataSet Accessors
![Page 57: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/57.jpg)
get_fields() get a list of MetaFields belonging to the dataset
get_types() get a list of all types in the dataset e.g. EPrint types: article, book, book_section,
conference_item, monograph, patent, thesis, other
e.g. User types: user, editor, admin get_type_name(session, type)
get a string containing a human-readable name for the specified type in current language
DataSet Accessors
![Page 58: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/58.jpg)
get_type_fields(type) get a list of MetaFields belonging to the
given type get_required_type_fields(type)
get a list of the MetaFields which are required for the given type
field_required_in_type(field, type)
true if given field is required in given type
DataSet Accessors
![Page 59: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/59.jpg)
render_name(session) get an XHTML fragment containing the
name of the dataset in the language of the current session
render_type_name(session, type) get an XHTML fragment containing the
name of the given type in the language of the session
Rendering DataSets
![Page 60: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/60.jpg)
render_name(session) get an XHTML fragment containing the
name of the field in the current language e.g. from phrases-en.xml: <ep:phrase ref="eprint_fieldname_title"> Title</ep:phrase>
Rendering MetaFields
![Page 61: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/61.jpg)
render_input_field(session, value)
get some XHTML containing input controls that will allow a user to input data to the field
value is the default value
Rendering MetaFields
![Page 62: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/62.jpg)
render_help(session, type) get some XHTML containing help text for a user
inputting some data for the field if an optional type is specified then specific
help for that type will be used if available e.g. from phrases-en.xml:
<ep:phrase ref="eprint_fieldhelp_title">The title of the item.</ep:phrase>
<ep:phrase ref="eprint_fieldhelp_title.book">The title of the book, usually found on the title page.</ep:phrase>
Rendering MetaFields
![Page 63: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/63.jpg)
We know how to access data objects in EPrints
EPrint, User, Document ...
We know how to access collections of these objects
Datasets MetaFields
Now, how do we search for items?
So Far...
![Page 64: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/64.jpg)
Searching Your Archive
SearchExpressions
![Page 65: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/65.jpg)
The conditions of a single search new(data)
create a new search expression from the given data
se = new SearchExpression( session => session,dataset => dataset,custom_order => “title” )
sorted by title, ascending
SearchExpression
![Page 66: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/66.jpg)
add_field(metafield, value) add a new search field with the given
value (search text) to the search expression
if the search field already exists in the search expression, its value is replaced
Adding Search Fields
![Page 67: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/67.jpg)
Example: full text search searchexp->add_field(
dataset->get_field(“title”),“routing”,“IN”,“ALL” )
Adding Search Fields
![Page 68: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/68.jpg)
Example: full text search matches word in title OR abstract searchexp->add_field(
[ ds->get_field(“title”),dataset->get_field(“abstract”) ],
“routing”,“IN”,“ALL” )
Adding Search Fields
![Page 69: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/69.jpg)
Example: date range search searchexp->add_field(
dataset->get_field(“date”),“2000-2004”,“EQ”,“ALL” )
Adding Search Fields
![Page 70: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/70.jpg)
serialise() get a text representation of the search
expression, for persistent storage from_string(string)
unserialises the contents of string but only into the fields already existing in
the SearchExpression
Serialising Searches
![Page 71: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/71.jpg)
render_description() get some XHTML describing the current
parameters of the search expression render_search_form(help)
render an input form for the search expression
if help is true then this also renders the help for each search field in current language
Rendering SearchExpressions
![Page 72: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/72.jpg)
Carry out a search using: perform_search()
The results can then be accessed: count()
get the number of results get_records(offset, count) get_ids(offset, count)
get a list of DataObjs (e.g. EPrint, User) representing the result set, or just their ids
optionally specify a range of results to return from result set using count and offset
Processing Results
![Page 73: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/73.jpg)
map(function, args) using get_records to get results uses a
lot of memory if there are 1000s of results
apply the function to each result without overhead
function is called with args: (session, dataset, dataobj, args)
the DataSet object also has a map function
creates a SearchExpression over dataset sets allow_blank = 1
passes args to searchexp->map
Processing Results
![Page 74: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/74.jpg)
Aside: Lists in EPrints 3.0
In EPrints 3.0, searches return a List ordered collection of DataObjs
In fact, any 2.3 function which returns a list (array) of DataObjs returns a List in 3.0
list->reorder( neworder ) list->union( list2 ) list->intersect( list2 ) list->remainder( list2 )
map over items in the list even arbitrarily constructed ones
![Page 75: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/75.jpg)
Scripting Your Repository
Archives and Sessions
![Page 76: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/76.jpg)
One EPrints installation can host multiple archives
An Archive object is a single EPrints archive
access archive-specific configuration
Don’t confuse the Archive object with the archive DataSet!
archive->get_dataset(“archive”) renamed Repository in 3.0
Archive
![Page 77: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/77.jpg)
get_id() get the id string of the archive.
get_conf(key, subkeys) get a named configuration setting probably set in ArchiveConfig.pm get_conf( "stuff", "en", "foo" )
Archive Accessors
![Page 78: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/78.jpg)
call(cmd, params) calls the subroutine named cmd specified
in the archive configuration (ArchiveConfig.pm etc.) with the given parameters and returns the result
can_call(cmd) true if the named cmd exists in the
archive configuration
lets you delegate processing to “user” space
Calling Archive Subs
![Page 79: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/79.jpg)
Session
Not a session in the traditional Web sense not stateful (although it might be in future!)
3.0 introduces cookie-based authentication global object which provides access to:
current language generic rendering functions CGI parameters (input from forms etc.) http request
Always create a session object at the beginning of your script
don’t forget to terminate it at the end
![Page 80: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/80.jpg)
new(mode, param) set mode to 0 for online session (CGI
script) uses language from cookie, http headers, or
default language
set mode to 1 for offline session (cmd line script)
param is the id of archive, uses default language
terminate() terminate session, performing necessary
cleanup
Creating & Ending a Session
![Page 81: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/81.jpg)
Web Page Building Blocks
make_doc_fragment() create an empty XHTML document fill it with things!
make_text(text) create an XML TextNode
make_element(name, attrs) create an XHTML Elementmake_element("p", align => "right")<p align=”right” />
![Page 82: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/82.jpg)
render_link(uri, target) create an XHTML linklink = session-> render_link("foo.html", "frame1")
link->appendChild(session-> make_text("Foo"))
<a href=”foo.html” target=”frame1”>Foo</a>
Web Page Building Blocks
![Page 83: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/83.jpg)
Many methods for building input forms, including:
render_form(method, dest) render_option_list(params) render_hidden_field(name, value) render_upload_field(name) render_action_buttons(buttons) ...
Web Page Building Blocks
![Page 84: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/84.jpg)
build_page(title, body) wraps your XHTML document in the
archive template send_page()
flatten page and send it to the user
Web Pages
![Page 85: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/85.jpg)
change_lang(langid) change the session language to the given
language ID phrase(phraseid, inserts)
get given phrase (as a string) in the current language
looks up phraseid in language-specific phrase file
e.g. phrases-en.xml
lets look at an example of the inserts parameter...
Language
![Page 86: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/86.jpg)
Language
html_phrase(phraseid, inserts) render an XHTML phrase in the current
languagesession->html_phrase( 'link_to_google', link => session-> render_link(“http://www.google.com”))
gets phrase link_to_google from phrases-en.xml
<ep:phrase><ep:pin ref="link">Search Google</ep:pin></ep:phrase>
<a href="http://www.google.com">Search Google</a>
![Page 87: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/87.jpg)
User Input
have_parameters true if parameters (POST or GET) were passed
to the CGI script (e.g. from an input form) param(name)
get the value of a parameter passed to the CGI script
get_action_button() get the id of the button the user pressed
client get the name of the user’s browser
![Page 88: Scripting EPrints. Light on syntax object->function(arg1, arg2) Incomplete Designed to give you a feel for the EPrints data model introduce](https://reader037.vdocuments.net/reader037/viewer/2022102818/56649f055503460f94c1aee7/html5/thumbnails/88.jpg)
Navigating the API