Jump to content
EPrints Documentation

Talk:API:EPrints

From EPrints Documentation
Revision as of 11:44, 10 September 2009 by Tdb01r (talk | contribs) (→XML)
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

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 ); # tdb: Unnecessary I think
$list = $dataset->list();
$dataset->list->map( sub {}, $ctx );

list

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

search

$search->add_field( %opts ); # better name needed?
$list = $search->execute();

XML

$utf8_string = $xml->to_string( $dom_node, %opts ); # tdb: pretty-print?
$utf8_string = $xml->to_xhtml( $dom_node, %opts ); # tdb: XHTML version?
$dom_node = $xml->parse_string( $string );
$dom_node = $xml->parse_file( $filename );
$dom_node = $xml->parse_url( $url );
$dom_node = $xml->clone( $dom_node [, $deep ] ); # tdb: $deep default=1?
$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...? tdb: not for ruler. Consistency vs. verbosity. Consistent (think 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()

Verbosity (without overloading the terms 'text' and 'comment'): 

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

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

These are CJG's notes, not part of the proposed API. 


$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 );
Retrieved from "https://wiki.eprints.org/w/index.php?title=Talk:API:EPrints&oldid=7334"