Difference between revisions of "Core API"

From EPrints Documentation
Jump to: navigation, search
m
 
(11 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
{{API}}
 
[[Category:API]]
 
[[Category:API]]
  
Line 6: Line 7:
  
 
=== Overview ===
 
=== Overview ===
 +
<source lang="perl">
 
  use EPrints;
 
  use EPrints;
 
  my $ep = EPrints->new();
 
  my $ep = EPrints->new();
 
  my $repo = $ep->repository( "myrepo" );
 
  my $repo = $ep->repository( "myrepo" );
 
  my $an_eprint = $repo->eprint( 23 );
 
  my $an_eprint = $repo->eprint( 23 );
 +
</source>
  
 
=== EPrints ===
 
=== EPrints ===
 +
<source lang="perl">
 
  $ep = EPrints->new();
 
  $ep = EPrints->new();
 
  @ids = $ep->repository_ids; # list active repository ids
 
  @ids = $ep->repository_ids; # list active repository ids
Line 17: Line 21:
 
  $repo = $ep->current_repository(); # from Apache::Request URI
 
  $repo = $ep->current_repository(); # from Apache::Request URI
 
  EPrints->abort( $message );
 
  EPrints->abort( $message );
 
+
</source>
 
=== Repository ===
 
=== Repository ===
$xml = $repo->xml;
+
<source lang="perl">
$dataset = $repo->dataset( "user" );
+
$xml = $repo->xml;
$user = $repo->current_user;
+
$dataset = $repo->dataset( "user" );
$query = $repo->query;
+
$user = $repo->current_user;
$current_page_url = $repo->current_url( host => 1, path => 1, query => 1, etc. );
+
$query = $repo->query;
$config_element = $repo->config( $key, [@subkeys] );
+
$current_page_url = $repo->current_url( host => 1, path => 1, query => 1, etc. );
$repository->log( $message );  
+
$config_element = $repo->config( $key, [@subkeys] );
$string = $repo->query->param( "X" );
+
$repository->log( $message );  
$repo->redirect( $url );
+
$string = $repo->query->param( "X" );
$eprint = $repo->eprint( 23 );
+
$repo->redirect( $url );
$user = $repo->user( 23 );
+
$eprint = $repo->eprint( 23 );
$user = $repo->user_by_username( "cjg" );
+
$user = $repo->user( 23 );
$user = $repo->user_by_email( 'cjg@ecs.soton.ac.uk' );
+
$user = $repo->user_by_username( "cjg" );
 +
$user = $repo->user_by_email( 'cjg@ecs.soton.ac.uk' );
 +
</source>
  
 
=== Dataset ===
 
=== Dataset ===
 +
<source lang="perl">
 
  $dataset = $repo->dataset( "eprint" )
 
  $dataset = $repo->dataset( "eprint" )
 
  $string = $dataset->base_id; # eprint
 
  $string = $dataset->base_id; # eprint
Line 41: Line 48:
 
   
 
   
 
  $dataobj = $dataset->create_dataobj( $data );
 
  $dataobj = $dataset->create_dataobj( $data );
  $user = $dataset->dataobj( 23 );
+
  $eprint = $dataset->dataobj( 23 );
 
   
 
   
 +
%options = (filters => [ { meta_fields => [ 'contributors_id' ], value => "13249", match=>"EX" } ]);
 
  $search = $dataset->prepare_search( %options );
 
  $search = $dataset->prepare_search( %options );
 
  $list = $dataset->search( %options ); # prepare_search( %options )->execute
 
  $list = $dataset->search( %options ); # prepare_search( %options )->execute
Line 55: Line 63:
 
  $ids = $dataset->search->ids;
 
  $ids = $dataset->search->ids;
 
  $list = $dataset->list( \@ids );
 
  $list = $dataset->list( \@ids );
 
+
</source>
 
=== list ===
 
=== list ===
 +
<source lang="perl">
 
  $n = $list->count;
 
  $n = $list->count;
  $list->map( sub {}, $ctx );
+
  $list->map( sub {
  $dataobj = $list->item( offset );
+
    my ( $repository, $dataset, $dataobj, $ctx ) = @_;
  @dataobjs = $list->slice( offset, length );  
+
    # do something to the dataobj here
 +
}, $ctx );
 +
  $dataobj = $list->item( $offset );
 +
@all_dataobjs = $list->slice
 +
  @dataobjs = $list->slice( $offset, $length );  
 
  \@ids = $list->ids;
 
  \@ids = $list->ids;
 
+
</source>
 
=== XML ===
 
=== XML ===
 +
<source lang="perl">
 
  $doc = $xml->parse_string( $string );
 
  $doc = $xml->parse_string( $string );
 
  $doc = $xml->parse_file( $filename );
 
  $doc = $xml->parse_file( $filename );
Line 84: Line 98:
 
   
 
   
 
  $xml->dispose( $dom_node );  
 
  $xml->dispose( $dom_node );  
 
+
</source>
 
=== XHTML ===
 
=== XHTML ===
 +
<source lang="perl">
 
  $xhtml = $repo->xhtml;
 
  $xhtml = $repo->xhtml;
 
   
 
   
 
  $utf8_string = $xhtml->to_xhtml( $dom_node, %opts ); # remove NS prefixes, fix <script> etc.
 
  $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.
+
  $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->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->text_area_field( $name, $value, %opts ); # tdb: value becomes a child text node  
Line 98: Line 113:
 
   
 
   
 
  $page = $xhtml->page( $map, %opts );
 
  $page = $xhtml->page( $map, %opts );
+
</source>
 
=== Page ===
 
=== Page ===
 +
<source lang="perl">
 
  $page->send( %options );  
 
  $page->send( %options );  
 
  $page->write_to_file( $filename );
 
  $page->write_to_file( $filename );
 
+
</source>
 
=== DataObj ===
 
=== DataObj ===
 
+
<source lang="perl">
 
  $dataobj = $dataset->dataobj( $id );
 
  $dataobj = $dataset->dataobj( $id );
 
  $dataobj->delete;
 
  $dataobj->delete;
Line 126: Line 142:
 
  $string = $dataobj->export( $plugin_id, %opts );
 
  $string = $dataobj->export( $plugin_id, %opts );
 
  $dataobj = $dataobj->create_subobject( $fieldname, $epdata );
 
  $dataobj = $dataobj->create_subobject( $fieldname, $epdata );
 
+
</source>
 
=== MetaField ===
 
=== MetaField ===
 
Now has a handle on both it's repository/session AND dataset.
 
Now has a handle on both it's repository/session AND dataset.
 
+
<source lang="perl">
 
  my $field = $dataset->field( $fieldname );
 
  my $field = $dataset->field( $fieldname );
 
   
 
   
Line 147: Line 163:
 
  $values = $field->all_values( %opts );
 
  $values = $field->all_values( %opts );
 
  $sorted_list = $field->sort_values( $unsorted_list );
 
  $sorted_list = $field->sort_values( $unsorted_list );
 +
</source>

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 );