Difference between revisions of "Template:API Content"
(Created page with "EPrints is written in the [http://www.perl.org/ Perl language]. Sometimes you may need to write your own Perl code using the EPrints Application Programming Interface (API)....") |
m (typos corrected) |
||
Line 3: | Line 3: | ||
Reasons you may need to write your own EPrints code: | Reasons you may need to write your own EPrints code: | ||
− | * customising the way the | + | * customising the way the Eprints summary pages are rendered |
* writing your own command-line script to control EPrints in some way | * writing your own command-line script to control EPrints in some way | ||
* writing a new CGI script (dynamic web page) | * writing a new CGI script (dynamic web page) | ||
Line 20: | Line 20: | ||
===[[API:EPrints/Repository|EPrints::Repository]]=== | ===[[API:EPrints/Repository|EPrints::Repository]]=== | ||
− | An | + | An repository is an eprints archive with its own website configuration and data. One install of the Eprints software can run several separate repositories. Sharing code but with totally different configurations. Before EPrints 2.4 this was known as EPrints::Archive. This was changed to avoid confusion with the eprint status of "archive". |
===[[API:EPrints/Database|EPrints::Database]]=== | ===[[API:EPrints/Database|EPrints::Database]]=== | ||
Line 51: | Line 51: | ||
|- | |- | ||
| subscription | | subscription | ||
− | | Subscriptions made by users. Every subscription is a part of a | + | | Subscriptions made by users. Every subscription is a part of a subscription record. |
|- | |- | ||
| history | | history | ||
Line 59: | Line 59: | ||
In addtion to these datasets are four virtual datasets: inbox, buffer, archive and deletion. These act just like "eprint" except that they are filtered to only contain records with those status. | In addtion to these datasets are four virtual datasets: inbox, buffer, archive and deletion. These act just like "eprint" except that they are filtered to only contain records with those status. | ||
− | Note that prior to 2.4 the "eprint" dataset was virtual, rather than "inbox", "buffer" etc. The | + | Note that prior to 2.4 the "eprint" dataset was virtual, rather than "inbox", "buffer" etc. The history dataset was introduced in 2.4. |
===[[API:EPrints/MetaField|EPrints::MetaField]]=== | ===[[API:EPrints/MetaField|EPrints::MetaField]]=== | ||
− | A single field in a dataset. Each dataset has a few "system" fields which | + | A single field in a dataset. Each dataset has a few "system" fields which Eprints uses to manage the system and then any number of ''archive'' specific fields which you may configure. |
===[[API:EPrints/DataObj|EPrints::DataObj]]=== | ===[[API:EPrints/DataObj|EPrints::DataObj]]=== | ||
Line 73: | Line 73: | ||
====[[API:EPrints/DataObj/Document|EPrints::DataObj::Document]]==== | ====[[API:EPrints/DataObj/Document|EPrints::DataObj::Document]]==== | ||
− | A document is a single format of an ''eprint'', | + | A document is a single format of an ''eprint'', e.g. HTML, PDF, PS etc. It can contain more than one file, for example HTML may contain more than one html page + image files. The actual files are stored in the filesystem. Pre 2.4 this was known as EPrints::Document. |
====[[API:EPrints/DataObj/EPrint|EPrints::DataObj::EPrint]]==== | ====[[API:EPrints/DataObj/EPrint|EPrints::DataObj::EPrint]]==== | ||
Line 81: | Line 81: | ||
====[[API:EPrints/DataObj/SavedSearch|EPrints::DataObj::SavedSearch]]==== | ====[[API:EPrints/DataObj/SavedSearch|EPrints::DataObj::SavedSearch]]==== | ||
− | Some software refers to this concept as | + | Some software refers to this concept as ''alerts''. |
− | A stored search which is performed every day/week/month and any new results are | + | A stored search which is performed every day/week/month and any new results are then mailed to the user who owns the subscription. |
− | This diagram does not show "Subscription". Subscription is a subclass of DataObj (like EPrint, User etc.). A | + | This diagram does not show "Subscription". Subscription is a subclass of DataObj (like EPrint, User etc.). A subscription is associated with one User. A user is associated with 0..n Subscription's. |
====[[API:EPrints/DataObj/Subject|EPrints::DataObj::Subject]]==== | ====[[API:EPrints/DataObj/Subject|EPrints::DataObj::Subject]]==== | ||
− | A ''subject'' has an id and a list of who | + | A ''subject'' has an id and a list of who its parents are. There is a built-in ''subject'' with the id "ROOT" to act as the top level. A subject can have more than one parent to allow you to create a rich lattice, rather than just a tree, but loops are not allowed. |
====[[API:EPrints/DataObj/User|EPrints::DataObj::User]]==== | ====[[API:EPrints/DataObj/User|EPrints::DataObj::User]]==== | ||
− | A user registered with the system. (NOT | + | A user registered with the system. (NOT necessarily the author of the ''eprint'' they deposit). Pre 2.4 this was known as EPrints::User |
Latest revision as of 16:24, 8 August 2019
EPrints is written in the Perl language. Sometimes you may need to write your own Perl code using the EPrints Application Programming Interface (API).
Reasons you may need to write your own EPrints code:
- customising the way the Eprints summary pages are rendered
- writing your own command-line script to control EPrints in some way
- writing a new CGI script (dynamic web page)
- writing a plugin
Contents
Key Sections
- Core API provides a basic introduction to using the EPrints API.
- StyleGuide gives guidance on how to code in a compatible style.
- Modules discusses the framework for Plugins you write for the community.
Principal Modules
This is a list of the principal modules in the EPrints API. These modules are the primary means of connecting to and manipulating objects in the repository.
EPrints::Repository
An repository is an eprints archive with its own website configuration and data. One install of the Eprints software can run several separate repositories. Sharing code but with totally different configurations. Before EPrints 2.4 this was known as EPrints::Archive. This was changed to avoid confusion with the eprint status of "archive".
EPrints::Database
The connection to the MySQL (or other database) back end. datasets are stored in the MySQL system, but you do not have to address it directly.
EPrints::DataSet
A dataset is a collection of items of the same type. It can be searched.
Some datasets all have the same "config id". The "config id" is used to get information about the dataset from the archive config - inbox, buffer, archive and deletion all have the same metadata fields and types.
Core datasets are:
DATASET ID | COMMENT |
eprint | EPrint records are the core of the system. |
user | Users registered with the system. |
subject | The subject tree. |
document | Documents belonging to EPrints. Every document is part of an EPrint record. |
subscription | Subscriptions made by users. Every subscription is a part of a subscription record. |
history | Stores actions performed on records. |
In addtion to these datasets are four virtual datasets: inbox, buffer, archive and deletion. These act just like "eprint" except that they are filtered to only contain records with those status.
Note that prior to 2.4 the "eprint" dataset was virtual, rather than "inbox", "buffer" etc. The history dataset was introduced in 2.4.
EPrints::MetaField
A single field in a dataset. Each dataset has a few "system" fields which Eprints uses to manage the system and then any number of archive specific fields which you may configure.
EPrints::DataObj
The "super class" of subjects, users, eprints and documents etc. In the very core of the system these are all treated identically and much of the configuration and methods of these classes of "thing" are identical. We use the term item to speak about the general case.
- type or user-type or eprint-type
- users, eprints and documents all have a "type". This controls how they are "cited" and also for users and eprints it controls what fields may be edited, and which are required.
EPrints::DataObj::Document
A document is a single format of an eprint, e.g. HTML, PDF, PS etc. It can contain more than one file, for example HTML may contain more than one html page + image files. The actual files are stored in the filesystem. Pre 2.4 this was known as EPrints::Document.
EPrints::DataObj::EPrint
An eprint is a record in the system which has one or more documents and some metadata. Usually, more than one document is to provide the same information in multiple formats, although this is not compulsory. Pre 2.4 this was known as EPrints::EPrint.
EPrints::DataObj::SavedSearch
Some software refers to this concept as alerts.
A stored search which is performed every day/week/month and any new results are then mailed to the user who owns the subscription.
This diagram does not show "Subscription". Subscription is a subclass of DataObj (like EPrint, User etc.). A subscription is associated with one User. A user is associated with 0..n Subscription's.
EPrints::DataObj::Subject
A subject has an id and a list of who its parents are. There is a built-in subject with the id "ROOT" to act as the top level. A subject can have more than one parent to allow you to create a rich lattice, rather than just a tree, but loops are not allowed.
EPrints::DataObj::User
A user registered with the system. (NOT necessarily the author of the eprint they deposit). Pre 2.4 this was known as EPrints::User