Difference between revisions of "Talk:API:EPrints"
(→Alternatives) |
|||
Line 39: | Line 39: | ||
$ep = EPrints->new(); | $ep = EPrints->new(); | ||
$repo = $ep->repository( "devel", noise=>1 ); | $repo = $ep->repository( "devel", noise=>1 ); | ||
− | + | $repo = $ep->current_repository(); # from Apache::Request URI | |
− | $repo = $ep->current_repository(); # | ||
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 = $ | + | $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->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. | |
− | |||
− | |||
− | |||
− | |||
$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 ); # | + | $list = $dataset->search( %options ); # prepare_search( %options )->execute |
− | $list = $dataset->search; # | + | $list = $dataset->search; # match ALL |
− | + | ||
− | |||
− | |||
− | |||
− | |||
$metafield = $dataset->field( $fieldname ); | $metafield = $dataset->field( $fieldname ); | ||
$metafield = $dataset->key_field; | $metafield = $dataset->key_field; | ||
@metafields = $dataset->fields; | @metafields = $dataset->fields; | ||
− | + | ||
− | |||
− | |||
$dataset->search->map( sub {}, $ctx ); | $dataset->search->map( sub {}, $ctx ); | ||
$n = $dataset->search->count; | $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 === | === 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 ); | |
− | + | @ids = $list->ids; | |
− | @dataobjs = $list->slice( offset, length ); | ||
− | |||
=== 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-> | + | $search->add_term( %opts ); # better name needed? |
− | $search-> | + | $search->add_term( $ds->get_field( "type" ), qw/ article book /, "EQ", "ANY" ); |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
==== 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, | + | $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 === | ||
− | |||
== 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)
Contents
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 );