Difference between revisions of "Core API"

From EPrints Documentation
Jump to: navigation, search
Line 1: Line 1:
 
[[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.
  
Core API modules.
+
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.  
* EPrint.pm - chris done
 
* DataObj.pm
 
* DataSet
 
* EPrint/EPrint
 
* EPrint/User
 
* EPrint/Subject
 
* EPrint/Document
 
* EPrint/File
 
* Handle
 
* Handle/Language.pm - patrick done
 
* Handle/Render.pm
 
* Handle/CGI.pm - seb doing
 
* Handle/Page.pm
 
* Handle/XML.pm -patrick doing
 
* Repository
 
* MetaField.pm
 
* List.pm
 
* Search.pm
 
* Database.pm
 
* Time.pm - patrick done
 
* URL.pm
 
* Utils.pm
 
* XML.pm -patrick done
 
  
Todo later.
+
=== Overview ===
* Paginate.pm
+
use EPrints;
* Paginate/Columns.pm
+
my $ep = EPrints->new();
* Box.pm
+
my $repo = $ep->repository( "myrepo" );
* Email.pm
+
my $an_eprint = $repo->eprint( 23 );
* Platform.pm
+
 
* Storage.pm
+
=== EPrints ===
* TempDir.pm
+
$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 );
 +
$user = $dataset->dataobj( 23 );
 +
 +
$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 {}, $ctx );
 +
$dataobj = $list->item( offset );
 +
@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.
 +
$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 );

Revision as of 11:59, 19 May 2010


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 );
$user = $dataset->dataobj( 23 );

$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 {}, $ctx );
$dataobj = $list->item( offset );
@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.
$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 );