Difference between revisions of "Talk:API:EPrints"

From EPrints Documentation
Jump to: navigation, search
(Alternatives)
Line 39: Line 39:
 
  $ep = EPrints->new();
 
  $ep = EPrints->new();
 
  $repo = $ep->repository( "devel", noise=>1 );
 
  $repo = $ep->repository( "devel", noise=>1 );
# $repo = EPrints->repository_from_request( noise=>3 );
+
  $repo = $ep->current_repository(); # from Apache::Request URI
  $repo = $ep->current_repository(); # tdb - OK [[User:Cjg|Cjg]] 17:20, 10 September 2009 (BST)
 
 
  EPrints->abort( $message );
 
  EPrints->abort( $message );
  
 
=== repo ===
 
=== repo ===
 +
Yes:
 
  $xml = $repo->xml;
 
  $xml = $repo->xml;
 
  $dataset = $repo->dataset( "user" );
 
  $dataset = $repo->dataset( "user" );
Line 49: Line 49:
 
  $query = $repo->query;
 
  $query = $repo->query;
 
  $current_page_url = $repo->current_url;  
 
  $current_page_url = $repo->current_url;  
  $config_element = $repository->config( $key, [@subkeys] );
+
  $config_element = $repo->config( $key, [@subkeys] );
  # tdb: language accessors
+
  $repository->log( $message );
 +
$string = $repo->query->param( "X" );
 +
$repo->redirect( $url );
 +
Maybe:
 +
* tdb: language accessors
 +
** cjg: I think thses don't belong in the API - why do people need access to them? If I'm wrong we add them in API 1.1?
 
  $lang = $repo->language( $langid );
 
  $lang = $repo->language( $langid );
 
  $lang = $repo->default_language; # needed? nee ->language( undef )
 
  $lang = $repo->default_language; # needed? nee ->language( undef )
 
  $lang = $repo->current_language;
 
  $lang = $repo->current_language;
 
+
* cjg: I think these would be very useful but they are inconsistent.
$repository->log( $message );
 
$string = $repo->query->param( "X" );
 
$repo->redirect( $url );
 
MAYBE:
 
 
  $eprint = $repo->eprint( 23 );
 
  $eprint = $repo->eprint( 23 );
 
  $user = $repo->user( 23 );
 
  $user = $repo->user( 23 );
 
  $user = $repo->user_by_username( "cjg" );
 
  $user = $repo->user_by_username( "cjg" );
 
  $user = $repo->user_by_email( 'cjg@ecs.soton.ac.uk' );
 
  $user = $repo->user_by_email( 'cjg@ecs.soton.ac.uk' );
 
 
=== dataset ===
 
=== dataset ===
 
  $string = $dataset->base_id; # eprint
 
  $string = $dataset->base_id; # eprint
 
  $string = $dataset->id; # inbox
 
  $string = $dataset->id; # inbox
 
 
  $dataobj = $datasset->create_dataobj( $data );
 
  $dataobj = $datasset->create_dataobj( $data );
 
  $user = $dataset->dataobj( 23 );
 
  $user = $dataset->dataobj( 23 );
 
+
 
  $search = $dataset->prepare_search( %options );
 
  $search = $dataset->prepare_search( %options );
  $list = $dataset->search( %options ); # tdb: == prepare_search( %options )->execute
+
  $list = $dataset->search( %options ); # prepare_search( %options )->execute
  $list = $dataset->search; # tdb: match ALL
+
  $list = $dataset->search; # 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->field( $fieldname );
 
  $metafield = $dataset->key_field;
 
  $metafield = $dataset->key_field;
 
  @metafields = $dataset->fields;  
 
  @metafields = $dataset->fields;  
  # $bool = $dataset->has_field( $fieldname ); # << do we need this?
+
   
 
 
# @ids = $dataset->ids; # tdb: conflict with ->id!
 
 
  $dataset->search->map( sub {}, $ctx );
 
  $dataset->search->map( sub {}, $ctx );
 
  $n = $dataset->search->count;  
 
  $n = $dataset->search->count;  
  eh, this last one doesn't make sense. do you mean $dataset->prepare_search(..)->execute->count ? [[User:Cjg|Cjg]] 12:30, 11 September 2009 (BST)
+
  $ids = $dataset->search->ids;
  tdb: ->search == ->prepare_search->execute, so $ds->count == $ds->search->count (avoid duplicating methods in List)
+
Maybe:
  etc.
+
* 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.
 +
$list = $dataset->list( \@ids );
 +
Maybe not:
 +
$bool = $dataset->has_field( $fieldname );
 +
   
 
=== list ===
 
=== list ===
 
  $n = $list->count();
 
  $n = $list->count();
 
  $list->map( sub {}, $ctx );
 
  $list->map( sub {}, $ctx );
 
  $dataobj = $list->item( offset );
 
  $dataobj = $list->item( offset );
 
+
  @dataobjs = $list->slice( offset, length );  
# tdb: should these return lists or array refs? c.f. $dataset->fields, $dataset->list( \@ids )
+
  @ids = $list->ids;
  @dataobjs = $list->slice( offset, length ); # nee get_records()
 
  \@ids = $list->ids;
 
  
 
=== search ===
 
=== search ===
Line 107: Line 102:
 
   
 
   
 
  # the below call needs replacing with something less sucky.
 
  # the below call needs replacing with something less sucky.
  $search->add_field( %opts ); # better name needed?
+
  $search->add_term( %opts ); # better name needed?
  $search->add_field( $ds->get_field( "type" ), qw/ article book /, "EQ", "ANY" );
+
  $search->add_term( $ds->get_field( "type" ), qw/ article book /, "EQ", "ANY" );
 
 
# tdb: add_field synomyms?
 
$search->add_term
 
$search->add_criteria
 
$search->add_query
 
$search->add_constraint
 
$search->constrain
 
$search->restrict
 
  
 
==== Alternatives ====
 
==== Alternatives ====
Line 134: Line 121:
  
 
  print $list->count, "\n";
 
  print $list->count, "\n";
 +
 +
* [[User:Cjg|Cjg]] 18:27, 16 September 2009 (BST) : I kinda like where this is going but don't like the ugly constants.
  
 
=== XML ===
 
=== XML ===
Line 164: Line 153:
 
  $xhtml_dom_node = $xml->render_nbsp;
 
  $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_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_name( $namehash, render_order=>"gf" ); # or fg
 
  $xhtml_dom_node = $xml->render_input_field( %opts ); # nb. noenter & hidden are now options.
 
  $xhtml_dom_node = $xml->render_input_field( %opts ); # nb. noenter & hidden are now options.
 
  $xhtml_dom_node = $xml->render_form( $method, $url );
 
  $xhtml_dom_node = $xml->render_form( $method, $url );
Line 173: Line 162:
 
  $page->send( %options );  
 
  $page->send( %options );  
 
  $page->write_to_file( $filename );
 
  $page->write_to_file( $filename );
 +
 +
=== DataObj ===
 +
 +
=== EPrint ===
 +
 +
=== User ===
 +
 +
=== Subject ===
 +
 +
=== Document ===
 +
 +
=== File ===
  
  
  
Still needing API working out: dataobj,eprint,user,subject,file,document
 
  
 
== Current ==
 
== Current ==

Revision as of 17:27, 16 September 2009

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

New Plan(!)

  • Merge Session and Repository into a single class.
  • Move XML functions into their own class.
  • Move Page functions into their own class.
  • Add a link to repository for dataset and metafield.
  • Ensure cleanup when repository object goes out of scope.
  • Make EPrints->new() return an eprints object which can pass out repository objects.
    • repository objects don't have a link to the EPrints object EVER.
    • When the eprints object is DESTROY'd it takes out the repositories, datasets and metafields etc.

EPrints

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

repo

Yes:

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

Maybe:

  • tdb: language accessors
    • cjg: I think thses don't belong in the API - why do people need access to them? If I'm wrong we add them in API 1.1?
$lang = $repo->language( $langid );
$lang = $repo->default_language; # needed? nee ->language( undef )
$lang = $repo->current_language;
  • cjg: I think these would be very useful but they are inconsistent.
$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 ); # 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;

Maybe:

  • 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.
$list = $dataset->list( \@ids ); 

Maybe not:

$bool = $dataset->has_field( $fieldname ); 

list

$n = $list->count();
$list->map( sub {}, $ctx );
$dataobj = $list->item( offset );
@dataobjs = $list->slice( offset, length ); 
@ids = $list->ids;

search

$search = $dataset->prepare_search( order => "-date", satisfy_all=>1 );
$search = $dataset->prepare_search( query => [], filters => [], ... );

$list = $search->execute();

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

Alternatives

I would like to make the value argument not automagically-split on ANY but explicitly use an array ref of values to match.

my $s = $dataset->prepare_search( order => "-date", satisfy_all => 1, query => [
 { fields => ["type"], values => [qw/article book/], merge => EPrints::Search::ANY },
 { fields => [qw( title abstract )], values => ["dogbert dilbert"], match => EPrints::Search::INDEX, merge => EPrints::Search::ALL },
 { fields => ["userid"], values => ["52"], match => EPrints::Search::EXACT },
] );
my $s = $dataset->prepare_search( order => "-date", satisfy_all => 1 );
$s->add_query( ["type"], [qw/article book/], merge => EPrints::Search::ANY );
$s->add_query( [qw( title abstract )], ["dogbert dilbert"], match => EPrints::Search::INDEX, merge => EPrints::Search::ALL );
$s->add_query( ["userid"], ["52"], match => EPrints::Search::EXACT );
my $list = $s->execute;

$s->add_query( [$dataset->get_field( "type" )], [qw/ article book/], merge => EPrints::Search::ANY );
print $list->count, "\n";
  • Cjg 18:27, 16 September 2009 (BST) : I kinda like where this is going but don't like the ugly constants.

XML

$doc = $xml->parse_string( $string );
$doc = $xml->parse_file( $filename );
$doc = $xml->parse_url( $url );
$utf8_string = $xml->to_string( $dom_node, %opts ); 
$utf8_string = $xml->to_plain_text( $dom_node, %opts ); # nee tree_to_utf8
$utf8_string = $xml->to_xhtml( $dom_node, %opts ); # remove NS prefixes, fix <script> etc.
$utf8_string = $xml->text_content( $dom_node ); # textual content?
$dom_node = $xml->clone( $dom_node ); # deep
$dom_node = $xml->clone_node( $dom_node ); # shallow
$dom_node = $xml->create_element( $name, %attr );
$dom_node = $xml->create_text_node( $value );
$dom_node = $xml->create_comment_node( $value );
$dom_node = $xml->create_document_fragment;
$xml->dispose( $dom_node );
$page = $xml->build_page( %opts );
$xhtml_dom_node = $xml->html_phrase( $phrase_id );
$utf8string = $xml->text_phrase( $phrase_id );
# tdb: move these to EPrints::XHTML and strip ^render_?
$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, render_order=>"gf" ); # or fg 
$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...?

Page

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

DataObj

EPrint

User

Subject

Document

File

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