Difference between revisions of "Core API"

From EPrints Documentation
Jump to: navigation, search
m
 
(19 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 +
{{API}}
 
[[Category:API]]
 
[[Category:API]]
  
−
{{api}}
+
The core API was introduced in EPrints 3.2.0 and is intended to provide a clean and consistent programming interface to the EPrints system.
  
−
This is the bits which you will need to get started...
+
Not all essential functionality is yet available in the new API, as we've only included functions which we are confident we can keep stable for a number of versions.  
  
−
A connection to the EPrints system is represented by an instance of [[API:EPrints/Session|EPrints::Session]]. The session object links to
+
=== Overview ===
−
* the configuration of the repository (only one per session object, even if the system itself has multiple repositories).
+
<source lang="perl">
−
* the database for the repository.
+
use EPrints;
−
* the language to output in.
+
my $ep = EPrints->new();
−
And if a CGI script then also
+
my $repo = $ep->repository( "myrepo" );
−
* the [[API:EPrints/DataObj/User|EPrints::DataObj::User]] object of the current user, if any.
+
my $an_eprint = $repo->eprint( 23 );
−
* the apache request.
+
</source>
  
−
If you're writing your own script then you'll need to start by asking for a Session object.
+
=== EPrints ===
 +
<source lang="perl">
 +
$ep = EPrints->new();
 +
@ids = $ep->repository_ids; # list active repository ids
 +
$repo = $ep->repository( "devel", noise=>1 );
 +
$repo = $ep->current_repository(); # from Apache::Request URI
 +
EPrints->abort( $message );
 +
</source>
 +
=== Repository ===
 +
<source lang="perl">
 +
$xml = $repo->xml;
 +
$dataset = $repo->dataset( "user" );
 +
$user = $repo->current_user;
 +
$query = $repo->query;
 +
$current_page_url = $repo->current_url( host => 1, path => 1, query => 1, etc. );
 +
$config_element = $repo->config( $key, [@subkeys] );
 +
$repository->log( $message );
 +
$string = $repo->query->param( "X" );
 +
$repo->redirect( $url );
 +
$eprint = $repo->eprint( 23 );
 +
$user = $repo->user( 23 );
 +
$user = $repo->user_by_username( "cjg" );
 +
$user = $repo->user_by_email( 'cjg@ecs.soton.ac.uk' );
 +
</source>
  
−
== Command-line Script ==
+
=== Dataset ===
−
 
+
<source lang="perl">
−
  #!/usr/bin/perl -w -I/opt/eprints3/perl-lib/
+
$dataset = $repo->dataset( "eprint" )
 +
$string = $dataset->base_id; # eprint
 +
$string = $dataset->id; # inbox
 +
 +
$repo = $dataobj->repository;
 +
 +
$dataobj = $dataset->create_dataobj( $data );
 +
$eprint = $dataset->dataobj( 23 );
 +
 +
%options = (filters => [ { meta_fields => [ 'contributors_id' ], value => "13249", match=>"EX" } ]);
 +
$search = $dataset->prepare_search( %options );
 +
$list = $dataset->search( %options ); # prepare_search( %options )->execute
 +
  $list = $dataset->search; # match ALL
 +
 +
$metafield = $dataset->field( $fieldname );
 +
$metafield = $dataset->key_field;
 +
@metafields = $dataset->fields;
 +
 +
$dataset->search->map( sub {}, $ctx );
 +
$n = $dataset->search->count;
 +
$ids = $dataset->search->ids;
 +
$list = $dataset->list( \@ids );
 +
</source>
 +
=== list ===
 +
<source lang="perl">
 +
$n = $list->count;
 +
$list->map( sub {
 +
    my ( $repository, $dataset, $dataobj, $ctx ) = @_;
 +
    # do something to the dataobj here
 +
}, $ctx );
 +
$dataobj = $list->item( $offset );
 +
@all_dataobjs = $list->slice
 +
@dataobjs = $list->slice( $offset, $length );
 +
\@ids = $list->ids;
 +
</source>
 +
=== XML ===
 +
<source lang="perl">
 +
$doc = $xml->parse_string( $string );
 +
$doc = $xml->parse_file( $filename );
 +
$doc = $xml->parse_url( $url );
 +
 +
$utf8_string = $xml->to_string( $dom_node, %opts );
 +
 +
$dom_node = $xml->clone( $dom_node ); # deep
 +
$dom_node = $xml->clone_node( $dom_node ); # shallow
 +
 +
$dom_node = $xml->contents_of( $dom_node ); # clone and return child nodes
 +
$utf8_string = $xml->text_contents_of( $dom_node ); # Return text child nodes as a string
 +
 +
$dom_node = $xml->create_element( $name, %attr );
 +
$dom_node = $xml->create_text_node( $value );
 +
$dom_node = $xml->create_comment( $value );
 +
$dom_node = $xml->create_document_fragment;
 +
 +
$bool = $xml->is( $dom_node, "Text" );
 +
 +
$xml->dispose( $dom_node );
 +
</source>
 +
=== XHTML ===
 +
<source lang="perl">
 +
$xhtml = $repo->xhtml;
 +
 +
$utf8_string = $xhtml->to_xhtml( $dom_node, %opts ); # remove NS prefixes, fix <script> etc.
 +
 +
$xhtml_dom_node = $xhtml->input_field( $name, $value, %opts ); # nb. type & noenter are now options. noenter prevents the enter being pressed in the input field using javascript
 +
$xhtml_dom_node = $xhtml->hidden_field( $name, $value, %opts ); # tdb: this is used *a lot* and is well defined
 +
$xhtml_dom_node = $xhtml->text_area_field( $name, $value, %opts ); # tdb: value becomes a child text node
 +
$xhtml_dom_node = $xhtml->form( $method, $url );
 +
 +
$xhtml_dom_node = $xhtml->data_element( $name, $value, %opts ); # tdb: render_data_element
 +
 +
$page = $xhtml->page( $map, %opts );
 +
</source>
 +
=== Page ===
 +
<source lang="perl">
 +
$page->send( %options );
 +
$page->write_to_file( $filename );
 +
</source>
 +
=== DataObj ===
 +
<source lang="perl">
 +
$dataobj = $dataset->dataobj( $id );
 +
$dataobj->delete;
 +
$dataobj->commit( $force );
 +
 +
$dataset = $dataobj->dataset;
 +
$repo = $dataobj->repository;
 +
 +
$id = $dataobj->id;
 +
$dataobj->set_value( $fieldname, $value );
 +
$value = $dataobj->value( $fieldname );
 +
\@value = $dataobj->value( $fieldname ); # multiple
 +
$boolean = $dataobj->is_set( $fieldname );
 +
 +
$xhtml = $dataobj->render_value( $fieldname );
 +
$xhtml = $dataobj->render_citation( $style, %opts );
 +
 +
$uri = $dataobj->uri;
 +
$url = $dataobj->url;
 +
 +
$string = $dataobj->export( $plugin_id, %opts );
 +
$dataobj = $dataobj->create_subobject( $fieldname, $epdata );
 +
</source>
 +
=== MetaField ===
 +
Now has a handle on both it's repository/session AND dataset.
 +
<source lang="perl">
 +
my $field = $dataset->field( $fieldname );
 +
 +
$dataset = $field->dataset;
 +
$repo = $field->repository;
 
   
 
   
−
  use EPrints;
+
  $field->set_property( $property, $value );
 +
$value = $field->property( $property );
 
   
 
   
−
  use strict;
+
  $name = $field->name;
 +
$type = $field->type;
 
   
 
   
−
  my $archive_id = $ARGV[0];
+
  $xhtml = $field->render_name;
−
  my $session = new EPrints::Session( 1, $archive_id );
+
  $xhtml = $field->render_help;
−
  exit( 1 ) unless( defined $session );
+
  $xhtml = $field->render_value_label( $value );
−
 
 
−
# do your stuff
 
−
 
 
−
$session->terminate;
 
−
 
 
−
The "1" passed to Session tells it that we're a normal script and not a CGI script.
 
−
 
 
−
The $archive_id value is taken from $ARGV[0] which is the first parameter on the commandline. You could hard-wire the value if you wanted.
 
−
 
 
−
The use of "-w" to produce warnings and "use strict" to prevent sloppy code is just good Perl-practice.
 
−
 
 
−
== CGI Script ==
 
−
 
 
−
This is similar to a command line script but you don't need the path to perl and the archive_id is not needed as it will work that out from the web-request.
 
−
 
 
−
use EPrints;
 
−
 
 
−
use strict;
 
−
 
 
−
my $session = new EPrints::Session;
 
−
exit( 0 ) unless( defined $session );
 
−
 
 
−
# do some stuff
 
−
 
 
−
# Return a result to browser (usually an HTML page)
 
 
   
 
   
−
  $session->terminate();
+
  $values = $field->all_values( %opts );
−
 
+
$sorted_list = $field->sort_values( $unsorted_list );
−
== Code in the EPrints Configuration Files ==
+
</source>
−
 
 
−
Such as eprint_render.pl or creating a new subroutine for render_single_value on a field.
 
−
 
 
−
These are always passed a $session so you don't need to create your own.
 
−
 
 
−
== Plugins ==
 
−
 
 
−
These are described in the section about plugins.
 

Latest revision as of 14:22, 27 March 2017

EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects

API: Core API

The core API was introduced in EPrints 3.2.0 and is intended to provide a clean and consistent programming interface to the EPrints system.

Not all essential functionality is yet available in the new API, as we've only included functions which we are confident we can keep stable for a number of versions.

Overview

 use EPrints;
 my $ep = EPrints->new();
 my $repo = $ep->repository( "myrepo" );
 my $an_eprint = $repo->eprint( 23 );

EPrints

 $ep = EPrints->new();
 @ids = $ep->repository_ids; # list active repository ids
 $repo = $ep->repository( "devel", noise=>1 );
 $repo = $ep->current_repository(); # from Apache::Request URI
 EPrints->abort( $message );

Repository

$xml = $repo->xml;
$dataset = $repo->dataset( "user" );
$user = $repo->current_user;
$query = $repo->query;
$current_page_url = $repo->current_url( host => 1, path => 1, query => 1, etc. );
$config_element = $repo->config( $key, [@subkeys] );
$repository->log( $message ); 
$string = $repo->query->param( "X" );
$repo->redirect( $url );
$eprint = $repo->eprint( 23 );
$user = $repo->user( 23 );
$user = $repo->user_by_username( "cjg" );
$user = $repo->user_by_email( 'cjg@ecs.soton.ac.uk' );

Dataset

 $dataset = $repo->dataset( "eprint" )
 $string = $dataset->base_id; # eprint
 $string = $dataset->id; # inbox
 
 $repo = $dataobj->repository;
 
 $dataobj = $dataset->create_dataobj( $data );
 $eprint = $dataset->dataobj( 23 );
 
 %options = (filters => [ { meta_fields => [ 'contributors_id' ], value => "13249", match=>"EX" } ]);
 $search = $dataset->prepare_search( %options );
 $list = $dataset->search( %options ); # prepare_search( %options )->execute
 $list = $dataset->search; # match ALL
 
 $metafield = $dataset->field( $fieldname );
 $metafield = $dataset->key_field;
 @metafields = $dataset->fields; 
 
 $dataset->search->map( sub {}, $ctx );
 $n = $dataset->search->count; 
 $ids = $dataset->search->ids;
 $list = $dataset->list( \@ids );

list

 $n = $list->count;
 $list->map( sub {
     my ( $repository, $dataset, $dataobj, $ctx ) = @_;
     # do something to the dataobj here
 }, $ctx );
 $dataobj = $list->item( $offset );
 @all_dataobjs = $list->slice 
 @dataobjs = $list->slice( $offset, $length ); 
 \@ids = $list->ids;

XML

 $doc = $xml->parse_string( $string );
 $doc = $xml->parse_file( $filename );
 $doc = $xml->parse_url( $url );
 
 $utf8_string = $xml->to_string( $dom_node, %opts );
 
 $dom_node = $xml->clone( $dom_node ); # deep
 $dom_node = $xml->clone_node( $dom_node ); # shallow
 
 $dom_node = $xml->contents_of( $dom_node ); # clone and return child nodes
 $utf8_string = $xml->text_contents_of( $dom_node ); # Return text child nodes as a string
 
 $dom_node = $xml->create_element( $name, %attr );
 $dom_node = $xml->create_text_node( $value );
 $dom_node = $xml->create_comment( $value );
 $dom_node = $xml->create_document_fragment;
 
 $bool = $xml->is( $dom_node, "Text" );
 
 $xml->dispose( $dom_node );

XHTML

 $xhtml = $repo->xhtml;
 
 $utf8_string = $xhtml->to_xhtml( $dom_node, %opts ); # remove NS prefixes, fix <script> etc.
 
 $xhtml_dom_node = $xhtml->input_field( $name, $value, %opts ); # nb. type & noenter are now options. noenter prevents the enter being pressed in the input field using javascript
 $xhtml_dom_node = $xhtml->hidden_field( $name, $value, %opts ); # tdb: this is used *a lot* and is well defined
 $xhtml_dom_node = $xhtml->text_area_field( $name, $value, %opts ); # tdb: value becomes a child text node 
 $xhtml_dom_node = $xhtml->form( $method, $url );
 
 $xhtml_dom_node = $xhtml->data_element( $name, $value, %opts ); # tdb: render_data_element
 
 $page = $xhtml->page( $map, %opts );

Page

 $page->send( %options ); 
 $page->write_to_file( $filename );

DataObj

 $dataobj = $dataset->dataobj( $id );
 $dataobj->delete;
 $dataobj->commit( $force );
 
 $dataset = $dataobj->dataset;
 $repo = $dataobj->repository;
 
 $id = $dataobj->id;
 $dataobj->set_value( $fieldname, $value );
 $value = $dataobj->value( $fieldname );
 \@value = $dataobj->value( $fieldname ); # multiple
 $boolean = $dataobj->is_set( $fieldname );
 
 $xhtml = $dataobj->render_value( $fieldname );
 $xhtml = $dataobj->render_citation( $style, %opts );
 
 $uri = $dataobj->uri;
 $url = $dataobj->url;
 
 $string = $dataobj->export( $plugin_id, %opts );
 $dataobj = $dataobj->create_subobject( $fieldname, $epdata );

MetaField

Now has a handle on both it's repository/session AND dataset. 

 my $field = $dataset->field( $fieldname );
 
 $dataset = $field->dataset;
 $repo = $field->repository;
 
 $field->set_property( $property, $value );
 $value = $field->property( $property );
 
 $name = $field->name;
 $type = $field->type;
 
 $xhtml = $field->render_name;
 $xhtml = $field->render_help;
 $xhtml = $field->render_value_label( $value );
 
 $values = $field->all_values( %opts );
 $sorted_list = $field->sort_values( $unsorted_list );
Retrieved from ‘https://wiki.eprints.org/w/index.php?title=Core_API&oldid=12295’