Difference between revisions of "Talk:API:EPrints"

From EPrints Documentation
Jump to: navigation, search
(rev. 3.)
Line 10: Line 10:
 
* DataSetHandle
 
* DataSetHandle
 
* Repository, MetaField and DataSet still exist but are not part of the API.
 
* Repository, MetaField and DataSet still exist but are not part of the API.
 
$handle = EPrint->get_repository_handle()
 
$dataset = $handle->get_dataset_handle()
 
$field = $dataset->get_field( "foo" )
 
$search = $dataset->get_search()
 
  
 
OK. The problems:
 
OK. The problems:
Line 22: Line 17:
 
* What $foo variable name to conventially use to refer to this item.
 
* What $foo variable name to conventially use to refer to this item.
  
==== revision 2 ====
 
 
$repo = EPrints->repository_by_id( "devel" );
 
$dataset = $repo->dataset( "user" );
 
$user = $repo->user( 23 );
 
$user = $repo->user_by_username( "cjg" );
 
$user = $dataset->dataobj( 23 );
 
$search = $dataset->search();
 
$list = $search->execute();
 
 
= rev. 3. =
 
 
== repo ==
 
== repo ==
 
  $repo = EPrints->repository( "devel", noise=>1 );
 
  $repo = EPrints->repository( "devel", noise=>1 );
 
  $repo = EPrints->repository_from_request( noise=>3 );
 
  $repo = EPrints->repository_from_request( noise=>3 );
 +
EPrints->abort( $message );
 
  $xml = $repo->xml();
 
  $xml = $repo->xml();
 
  $dataset = $repo->dataset( "user" );
 
  $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( 23 );
 
  $user = $repo->user_by_username( "cjg" );
 
  $user = $repo->user_by_username( "cjg" );
Line 43: Line 37:
 
== dataset ==
 
== dataset ==
 
  $user = $dataset->dataobj( 23 );
 
  $user = $dataset->dataobj( 23 );
  $search = $dataset->prepare_search();
+
  $search = $dataset->prepare_search( %options );
 +
$list = $dataset->( @ids );
 
== search ==
 
== search ==
 
  $list = $search->execute();
 
  $list = $search->execute();
 +
== XML ==
 +
$utf8_string = $xml->to_string( $dom_node );
 +
$dom_node = $xml->parse_string( $string );
 +
$dom_node = $xml->parse_file( $filename );
 +
$dom_node = $xml->parse_url( $url );
 +
$dom_node = $xml->clone( $dom_node );
 +
$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 );
 +
$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 );
 +
Could we shorten this to $xml->ruler $xml->text etc...?
 +
=== Not in API? ===
 +
is_dom?
 +
write_xhtml_file
 +
== Page ==
 +
$page->send( %options );
 +
$page->write_to_file( $filename );
 +
== Search ==
 +
$search = $dataset->prepare_search( order => "-date", satisfy_all=>1 );
 +
# the below call needs replacing with something less sucky.
 +
$search->add_field( $ds->get_field( "type" ), qw/ article book /, "EQ", "ANY" );
 +
$list = $search->execute;
  
 +
Still needing API working out: dataobj,eprint,user,subject,file,document,search,list,page
 +
 +
== Current ==
 +
 +
 +
$new_list = $list->reorder( "-creation_date" ); # makes a new list ordered by reverse order creation_date
 +
 +
$new_list = $list->union( $list2, "creation_date" ) # makes a new list by adding the contents of $list to $list2. the resulting list is ordered by "creation_date"
 +
 +
$new_list = $list->remainder( $list2, "title" ); # makes a new list by removing the contents of $list2 from $list orders the resulting list by title
 +
 +
$n = $list->count() # returns the number of items in the list
 +
 +
@dataobjs = $list->get_records( 0, 20 );  #get the first 20 DataObjs from the list in an array
 +
 +
$list->map( $function, $info ) # performs a function on every item in the list. This is very useful go and look at the detailed description.
 +
 +
$plugin_output = $list->export( "BibTeX" ); #calls Plugin::Export::BibTeX on the list.
 +
 +
$dataset = $list->get_dataset(); #returns the dataset in which the containing objects belong
 +
  
  
Still needing API working out: dataobj,eprint,user,subject,file,document,search,list,xml,page
 
  
== Current ==
 
  
  $string = EPrints::XML::to_string( $node, "utf-8", 1 ); #use this to convert DOM trees to string
+
  my $field = $dataset->get_field( $fieldname );
 +
 +
# you must clone a field to modify any properties
 +
$newfield = $field->clone;
 +
$newfield->set_property( $property, $value );
 
   
 
   
  $dom = EPrints::XML::parse_xml_string( $string );
+
  $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)
 
   
 
   
  $dom = EPrints::XML::parse_xml( $file, $basepath, $no_expand );
+
  $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 );
 
   
 
   
  $boolean = is_dom( $node, @nodestrings );
+
  $values = $field->get_values( $handle, $dataset, %opts );
 
   
 
   
  $newnode = EPrints::XML::clone_node( $node, $deep );
+
  $sorted_list = $field->sort_values( $handle, $unsorted_list );
 +
 
 +
 
 +
 
 +
my $ds = $handle->get_dataset( "inbox" );
 +
my $ds = $repository->get_dataset( "inbox" );
 
   
 
   
  EPrints::XML::write_xhtml_file( $node, $filename );
+
  $confid = $ds->confid; # eprint
 +
$id = $ds->id;        # inbox
 
   
 
   
  $document = EPrints::XML::make_document();
+
  $metafield = $ds->get_field( $fieldname );
 +
$metafield = $ds->get_key_field;
 +
$bool = $ds->has_field( $fieldname );
 +
@metafields = $ds->get_fields;
 
   
 
   
  $dom = EPrints:XML::parse_url($url, $no_expand);
+
  $n = $ds->count( $handle );
 +
$ds->map( $handle, $fn, $info );
 +
@ids = $dataset->get_item_ids( $handle );
 +
 +
$obj = $ds->create_object( $handle, $data );
 +
 
 +
 
 +
 
 +
 
 +
 
 +
 
 +
 
 +
 
 +
 
  
 
nherrits all methods from EPrints::DataObj.
 
nherrits all methods from EPrints::DataObj.
Line 113: Line 193:
 
  $xhtml = $doc->render_icon_link( %opts );
 
  $xhtml = $doc->render_icon_link( %opts );
 
  $xhtml = $doc->render_preview_link( %opts );
 
  $xhtml = $doc->render_preview_link( %opts );
 
 
$repository = $handle->get_repository;
 
 
# without a $handle available
 
$repository = EPrints->get_repository( $id );
 
 
$id = $repository->get_id;
 
$dataset = $repository->get_dataset( $setname );
 
 
$repository->log( $msg );
 
 
$confitem = $repository->get_conf( $key, [@subkeys] );
 
 
# calling subtroutines in the config 
 
$boolean = $repository->can_call( @cmd_conf_path );
 
$result = $repository->call( $cmd, @params );
 
 
# calling external commands
 
$returncode = $repository->exec( $cmd_id, %map );
 
 
$img_dom = $handle->make_element( "img", src => "/foo.gif", alt => "my pic" );
 
 
$comment_dom = $handle->make_comment( $text );
 
 
$text_dom = $handle->make_text( $text );
 
 
$empty_frag = $handle->make_doc_fragment;
 
 
render_ruler
 
render_nbsp
 
render-link
 
render_name
 
$xhtml_hidden = $handle->render_hidden_field( $name, $value )
 
[edit] $xhtml_input = $handle->render_input_field( %opts )
 
[edit] $xhtml_input = $handle->render_noenter_input_field( %opts )
 
render_form
 
 
$handle->prepare_page( { page=>$mypage, title=>$mytitle } );
 
$handle->send_page();
 

Revision as of 11:06, 10 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

Session, Repository, DataSet, MetaField

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.

repo

$repo = EPrints->repository( "devel", noise=>1 );
$repo = EPrints->repository_from_request( noise=>3 );
EPrints->abort( $message );
$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

$user = $dataset->dataobj( 23 );
$search = $dataset->prepare_search( %options );
$list = $dataset->( @ids );

search

$list = $search->execute();

XML

$utf8_string = $xml->to_string( $dom_node );
$dom_node = $xml->parse_string( $string );
$dom_node = $xml->parse_file( $filename );
$dom_node = $xml->parse_url( $url );
$dom_node = $xml->clone( $dom_node );
$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 );
$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 );

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

Not in API?

is_dom?
write_xhtml_file

Page

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

Search

$search = $dataset->prepare_search( order => "-date", satisfy_all=>1 );
# the below call needs replacing with something less sucky.
$search->add_field( $ds->get_field( "type" ), qw/ article book /, "EQ", "ANY" );
$list = $search->execute;

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

Current

$new_list = $list->reorder( "-creation_date" ); # makes a new list ordered by reverse order creation_date

$new_list = $list->union( $list2, "creation_date" ) # makes a new list by adding the contents of $list to $list2. the resulting list is ordered by "creation_date"

$new_list = $list->remainder( $list2, "title" ); # makes a new list by removing the contents of $list2 from $list orders the resulting list by title

$n = $list->count() # returns the number of items in the list

@dataobjs = $list->get_records( 0, 20 );  #get the first 20 DataObjs from the list in an array

$list->map( $function, $info ) # performs a function on every item in the list. This is very useful go and look at the detailed description.

$plugin_output = $list->export( "BibTeX" ); #calls Plugin::Export::BibTeX on the list.

$dataset = $list->get_dataset(); #returns the dataset in which the containing objects belong



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


my $ds = $handle->get_dataset( "inbox" );
my $ds = $repository->get_dataset( "inbox" );

$confid = $ds->confid; # eprint
$id = $ds->id;         # inbox

$metafield = $ds->get_field( $fieldname );
$metafield = $ds->get_key_field;
$bool = $ds->has_field( $fieldname );
@metafields = $ds->get_fields;

$n = $ds->count( $handle );
$ds->map( $handle, $fn, $info );
@ids = $dataset->get_item_ids( $handle );

$obj = $ds->create_object( $handle, $data );






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