Jump to content
EPrints Documentation

Talk:API:EPrints

From EPrints Documentation
Revision as of 11:31, 11 September 2009 by Cjg (talk | contribs) (→dataset)
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

I'm going to use this page to get my thoughts in order. Cjg 16:58, 2 September 2009 (BST)

Current 3.1 System

Unsessioned Classes

These classes don't store a session internally resulting in methods like $foo->render( $session, ARGS ).

  • Repository
  • DataSet
  • MetaField
  • Language

Sessioned Classes

These classes store a session internally resulting in methods like $foo->render( ARGS ).

  • Session
  • DataObj
  • Plugin
  • List
  • Search
  • Database
  • Workflow
  • ScreenProcessor

API

Plan:

  • RepositoryHandle (was Session)
  • MetaFieldHandle
  • DataSetHandle
  • Repository, MetaField and DataSet still exist but are not part of the API.

OK. The problems:

  • what to name the new modules
  • if we should rename the old modules? s/DataSet/DataSetConfig/
  • What methods to use
  • What $foo variable name to conventially use to refer to this item.

EPrints

$ep = EPrints->new();
$repo = $ep->repository( "devel", noise=>1 );
# $repo = EPrints->repository_from_request( noise=>3 );
$repo = $ep->current_repository(); # tdb - OK Cjg 17:20, 10 September 2009 (BST)
EPrints->abort( $message );

repo

$xml = $repo->xml();
$dataset = $repo->dataset( "user" );
$repository->log( $message ); 
$config_element = $repository->config( $key, [@subkeys] );
$user = $repo->current_user;
$query = $repo->query;
$string = $repo->query->param( "X" );
$repo->redirect( $url );
$current_page_url = $repo->current_url;

MAYBE: 

$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

$string = $dataset->base_id; # eprint
$string = $dataset->id; # inbox

$dataobj = $datasset->create_dataobj( $data );
$user = $dataset->dataobj( 23 );

$search = $dataset->prepare_search( %options );
$list = $dataset->search( %options ); # tdb: search/execute
$list = $dataset->search; # tdb: match ALL
# $list = $dataset->list( \@ids ); 
# tdb: is this common enough to replace EPrints::List->new()? 
#  cjg: part of the API goal IMO is to get away from classnames if at all possible, so
#   this would become the proper way to create a list object.

$metafield = $dataset->field( $fieldname );
$metafield = $dataset->key_field;
@metafields = $dataset->fields; 
# $bool = $dataset->has_field( $fieldname ); # << do we need this?

# @ids = $dataset->ids; # tdb: conflict with ->id!
$dataset->search->map( sub {}, $ctx );
$n = $dataset->search->count; 
eh, this last one doesn't make sense. do you mean $dataset->prepare_search(..)->execute->count ? Cjg 12:30, 11 September 2009 (BST)
etc.

list

$list->count();
$list->map( sub {}, $ctx );
$list->item( offset );
$list->slice( offset, length ); # nee get_records()
$list->ids;

search

$search = $dataset->prepare_search( order => "-date", satisfy_all=>1 );

$list = $search->execute();

# the below call needs replacing with something less sucky.
$search->add_field( %opts ); # better name needed?
$search->add_field( $ds->get_field( "type" ), qw/ article book /, "EQ", "ANY" );

XML

$doc = $xml->parse_string( $string );
$doc = $xml->parse_file( $filename );
$doc = $xml->parse_url( $url );

$utf8_string = $xml->to_string( $dom_node, %opts ); # tdb: pretty-print? cjg: this output XML, we also need the tree_to_utf8 moved here.
$utf8_string = $xml->to_xhtml( $dom_node, %opts ); # tdb: XHTML version? cjg: what's the difference?

$dom_node = $xml->clone( $dom_node );
$dom_node = $xml->deep_clone( $dom_node );

deep_clone is the usual action. I'd be tempted to have clone and clone_node Cjg 11:51, 11 September 2009 (BST) 

$dom_node = $xml->make_element( $element_name, %attributes );
$dom_node = $xml->make_text( $utf8string );
$dom_node = $xml->make_comment( $utf8string )
$dom_node = $xml->make_doc_fragment;

$page = $xml->build_page( %opts );

$xhtml_dom_node = $xml->html_phrase( $phrase_id );
$utf8string = $xml->text_phrase( $phrase_id );

$xhtml_dom_node = $xml->render_ruler;
$xhtml_dom_node = $xml->render_nbsp;
$xhtml_dom_node = $xml->render_link( $url, %opts ); #nb will require clever hack if scalar @opts = 1;
$xhtml_dom_node = $xml->render_name( $namehash, $familylast ); # I'd like to get away from boolean params -- too confusing!
$xhtml_dom_node = $xml->render_input_field( %opts ); # nb. noenter & hidden are now options.
$xhtml_dom_node = $xml->render_form( $method, $url );

Could we shorten this to $xml->ruler $xml->text etc...?

Alternatives

tdb: not for ruler. Consistency vs. verbosity. Consistent (c.f. create_dataobj): 

$dom_node = $xml->create_element()
$dom_node = $xml->create_text_node()
$dom_node = $xml->create_comment_node()
$dom_node = $xml->create_document_fragment()
 I think this isn't bad Cjg 17:21, 10 September 2009 (BST)

Verbosity (I think 'text' and 'comment' would become confusing/overloaded): 

$dom_node = $xml->element()
$dom_node = $xml->text_node()
$dom_node = $xml->comment_node()
$dom_node = $xml->document_fragment()

(doc_fragment has caught me out countless times - inconsistent abbreviation!)

Page

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


Still needing API working out: dataobj,eprint,user,subject,file,document

Current

my $field = $dataset->get_field( $fieldname );

# you must clone a field to modify any properties
$newfield = $field->clone;
$newfield->set_property( $property, $value );

$name = $field->get_name;
$type = $field->get_type;
$value = $field->get_property( $property );
$boolean = $field->is_type( @typenames );
$results = $field->call_property( $property, @args ); 
# (results depend on what the property sub returns)

$xhtml = $field->render_name( $handle );
$xhtml = $field->render_help( $handle );
$xhtml = $field->render_value( $handle, $value, $show_all_langs, $dont_include_links, $object );
$xhtml = $field->render_single_value( $handle, $value );
$xhtml = $field->get_value_label( $handle, $value );

$values = $field->get_values( $handle, $dataset, %opts );

$sorted_list = $field->sort_values( $handle, $unsorted_list );




nherrits all methods from EPrints::DataObj. 

# create a new document on $eprint 
my $doc_data = {
  _parent => $eprint,
  eprintid => $eprint->get_id,
};
my $doc_ds = $handle->get_dataset( 'document' );
my $document = $doc_ds->create_object( $handle, $doc_data );

# Add files to the document  
$success = $doc->add_file( $file, $filename, [$preserve_path] );
$success = $doc->upload( $filehandle, $filename [, $preserve_path [, $filesize ] ] );
$success = $doc->upload_archive( $filehandle, $filename, $archive_format );
$success = $doc->add_archive( $file, $archive_format );
$success = $doc->add_directory( $directory );
$success = $doc->upload_url( $url );

# get an existing document
$document = $handle->get_document( $doc_id );
# or
foreach my $doc ( $eprint->get_all_documents ) { ... }

# eprint to which this document belongs
$eprint = $doc->get_eprint;

# delete a document object *forever*:
$success = $doc->remove;

$url = $doc->get_url( [$file] );
$path = $doc->local_path;
%files = $doc->files;

# delete a file
$success = $doc->remove_file( $filename );
# delete all files
$success = $doc->remove_all_files;

# change the file which is used as the URL for the document.
$doc->set_main( $main_file );

# icons and previews
$xhtml = $doc->render_icon_link( %opts );
$xhtml = $doc->render_preview_link( %opts );
Retrieved from "https://wiki.eprints.org/w/index.php?title=Talk:API:EPrints&oldid=7360"