Editing Talk:API:EPrints (section)

== Stage 1.0 API ==

This is still required to make the basic API complete, but we'll worry about once we've got the stuff above finalisedish.

=== search ===
 TERM_EQUALS = "EQ"
 TERM_INDEX = "IN"
 TERM_EXACT = "EX"
 
 MATCH_ALL = "ALL"
 MATCH_ANY = "ANY"
 
 $search = $dataset->prepare_search( order => "-date", satisfy_all=>1 );
 $search = $dataset->prepare_search( terms => [], filters => [], ... );
 
 $list = $search->execute;
 
 # constructor interface
 $s = $dataset->prepare_search( order => "-date", satisfy_all => 1, terms => [
  { fields => "type", values => [qw( article book )], op => TERM_EQUALS, match => MATCH_ANY },
  { fields => [qw( title abstract )], values => ["dogbert dilbert"], op => TERM_INDEX, match => MATCH_ALL },
  { fields => "userid", values => "52", op => TERM_EXACT },
 ] );
* tdb: meta_fields/fields/field, value/values?
** cjg: could have choice of fields=>["",""] or field=>""

 # method interface
 $s = $dataset->prepare_search( order => "-date", satisfy_all => 1 );
 $s->add_term( "type", [qw( article book )], op => TERM_EQUALS, match => MATCH_ANY );
 $s->add_term( [qw( title abstract )], ["dogbert dilbert"], op => TERM_INDEX, match => MATCH_ALL );
 $s->add_term( "userid", "52", op => TERM_EXACT );
 $list = $s->execute;
 
 print $list->count, "\n";

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

==== Maybe ====
 $s->add_term( $dataset->field( "type" ), [qw/ article book/], merge => MERGE_ANY );
* cjg: I'm not convinced we need this.

=== SubObject ===
* tdb: superclass of Document, File, History, SavedSearch
 $dataobj = $dataobj->parent;

=== EPrint ===

 $eprint->set_status( "inbox" );

* tdb: consistency - ->documents ~ ->value( "documents" ) and ->value() returns array ref for multiple
 my $docs = $eprint->documents( %opts ); # isVolatileVersionOf => 0 ?
 foreach my $document ( @$docs ) { .. }
 
 # create a new document on $eprint 
 $doc_data = { ... };
 $doc = $eprint->create_subobject( "documents", $doc_data ); 
 # eprint to which this document belongs
 $eprint = $doc->parent;

=== User ===
 $user = $repository->dataset( "user" )->dataobj( 23 ); 
* tdb: is this accessor or action? c.f. send_page()
** It's an action. [[User:Cjg|Cjg]] 20:04, 17 September 2009 (BST)
 $user->send_email( .... )

=== Subject ===

 $subject = $repository->dataset("subject")->dataobj( "FOO" );
 \@subjects = $subject->children;
 \@subjects = $subject->parents; 
* CJG: issue with confusion with subobjects like document, or are these really subobjects? Maybe child_subjects parent_subjects to avoid overlapping names?
* tdb: subobject relation = if you remove parent, children are removed - is this true of subjects? Could extend subobject concept to be M:N
** $subject->value( "children" ) = ->children
** $subject->value( "parents" ) = ->parents

=== Document ===
 $doc = $repo->dataset( "document" )->dataobj( 23 );
 
 # delete a document object *forever*:
 $ok = $doc->delete;
 
 $url = $doc->url( [$file] );
* tdb: is $file ^^ a file object or filename?
** [[User:Cjg|Cjg]] 20:05, 17 September 2009 (BST): Duh, we should just use $doc->file_by_filename( $file )->get_url;

 # change the file which is used as the URL for the document.
 $doc->set_value( "main", "foo.html" );
 
 # dealing with files
 $file = $doc->file_by_filename( $filename ); # nee get_stored_file
 \@files = $doc->value( "files" );
 $file->value( "filename" );
 $file->value( "filesize" );
 
 # delete a file
 $doc->file_by_filename( $filename )->delete;
 
 # delete all files
 $files = $doc->value( "files" );
 foreach my $file (@$files) { $file->delete; } 
 
 # icons and previews???? These need work!
 $xhtml = $doc->render_icon_link( %opts );
 $xhtml = $doc->render_preview_link( %opts );

==== Maybe ====
 # Add files to the document
 # tdb: these should be deprecated from Document and moved to Import/Screen plugins
 $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 );

=== File ===
 $file = $history->file_by_filename( "dataobj.xml" );
 $file->retrieve( sub { ... }, $info ); # callback-based file content retrieval

* I don't know enough about this method to know what we *must* have in. Less is better IMO, though. [[User:Cjg|Cjg]] 01:23, 17 September 2009 (BST)
* tdb: files should probably be only created via a parent object