Difference between revisions of "API:EPrints/DataObj/Subject"

From EPrints Documentation
Jump to: navigation, search
(New page: <!-- Pod2Wiki=_preamble_ This page has been automatically generated from the EPrints source. Any wiki changes made between the 'Pod2Wiki=*' and 'End of Pod2Wiki' comments will be lost. -...)
 
(Removing all content from page)
Line 1: Line 1:
<!-- Pod2Wiki=_preamble_
 
This page has been automatically generated from the EPrints source. Any wiki changes made between the 'Pod2Wiki=*' and 'End of Pod2Wiki' comments will be lost.
 
-->{{Pod2Wiki}}{{API:Source|file=EPrints/DataObj/Subject.pm|package_name=EPrints::DataObj::Subject}}[[Category:API|Subject]]<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_name -->=NAME=
 
'''EPrints::DataObj::Subject''' - Class and methods relating to the subejcts tree.
 
  
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_description -->=DESCRIPTION=
 
This class represents a single node in the subejcts tree. It also contains a number of methods for handling the entire tree.
 
 
EPrints::DataObj::Subject is a subclass of EPrints::DataObj
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_system_field_info -->==get_system_field_info==
 
 
  $thing = EPrints::DataObj::Subject-&gt;get_system_field_info
 
 
Return an array describing the system metadata of the Subject dataset.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_new -->==new==
 
 
  $subject = EPrints::DataObj::Subject-&gt;new( $session, $subjectid )
 
 
Create a new subject object given the id of the subject. The values for the subject are loaded from the database.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_new_from_data -->==new_from_data==
 
 
  $subject = EPrints::DataObj::Subject-&gt;new_from_data( $session, $data )
 
 
Construct a new subject object from a hash reference containing the relevant fields. Generally this method is only used to construct new Subjects coming out of the database.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_commit -->==commit==
 
 
  $success = $subject-&gt;commit( [$force] )
 
 
Commit this subject to the database, but only if any fields have  changed since we loaded it.
 
 
If $force is set then always commit, even if there appear to be no changes.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_remove -->==remove==
 
 
  $success = $subject-&gt;remove
 
 
Remove this subject from the database.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_remove_all -->==remove_all==
 
 
  EPrints::DataObj::Subject::remove_all( $session )
 
 
Static function.
 
 
Remove all subjects from the database. Use with care!
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_create_child -->==create_child==
 
 
  $child_subject = $subject-&gt;create_child( $id, $name, $depositable )
 
 
Similar to EPrints::DataObj::Subject::create, but this creates the new subject as a child of the current subject.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_children -->==get_children==
 
 
  @children = $subject-&gt;get_children
 
 
Return a list of EPrints::DataObj::Subject objects which are direct children of the current subject.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_parents -->==get_parents==
 
 
  @parents = $subject-&gt;get_parents
 
 
Return a list of EPrints::DataObj::Subject objects which are direct parents of the current subject.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_can_post -->==can_post==
 
 
  $boolean = $subject-&gt;can_post( [$user] )
 
 
Determines whether the given user can post in this subject.
 
 
Currently there is no way to configure subjects for certain users, so this just returns the true or false depending on the "depositable" flag.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_with_path -->==render_with_path==
 
 
  $xhtml = $subject-&gt;render_with_path( $session, $topsubjid )
 
 
Return the name of this subject including it's path from $topsubjid.
 
 
$topsubjid must be an ancestor of this subject.
 
 
eg.
 
 
Library of Congress &gt; B Somthing &gt; BC Somthing more Detailed
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_paths -->==get_paths==
 
 
  @paths = $subject-&gt;get_paths( $session, $topsubjid )
 
 
This function returns all the paths from this subject back up to the specified top subject.
 
 
@paths is an array of array references. Each of the inner arrays is a list of subject id's describing a path down the tree from $topsubjid to $session.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_subjects -->==get_subjects==
 
 
  $subject_pairs = $subject-&gt;get_subjects ( [$postable_only], [$show_top_level], [$nes_tids], [$no_nest_label] )
 
 
Return a reference to an array. Each item in the array is a two  element list.
 
 
The first element in the list is an indenifier string.
 
 
The second element is a utf-8 string describing the subject (in the  current language), including all the items above it in the tree, but only as high as this subject.
 
 
The subjects which are returned are this item and all its children,  and childrens children etc. The order is it returns  this subject, then the first child of this subject, then children of  that (recursively), then the second child of this subject etc.
 
 
If $postable_only is true then filter the results to only contain  subjects which have the "depositable" flag set to true.
 
 
If $show_top_level is not true then the pair representing the current subject is not included at the start of the list.
 
 
If $nest_ids is true then each then the ids retured are nested so that the ids of the children of this subject are prefixed with this  subjects id and a colon, and their children are prefixed by their  nested id and a colon. eg. L:LC:LC003 rather than just "LC003"
 
 
if $no_nest_label is true then the subject label only contains the name of the subject, not the higher level ones.
 
 
A default result from this method would look something like this:
 
 
  [
 
    [ "D", "History" ],
 
    [ "D1", "History: History (General)" ],
 
    [ "D111", "History: History (General): Medieval History" ]
 
]
 
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_subject_label -->==subject_label==
 
 
  $label = EPrints::DataObj::Subject::subject_label( $session, $subject_id )
 
 
Return the full label of a subject, including parents. Returns undef if the subject id is invalid.
 
 
The returned string is encoded in utf8.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_all -->==get_all==
 
 
  ( $subject_map, $reverse_map ) = EPrints::DataObj::Subject::get_all( $session )
 
 
Get all the subjects for the current archvive of $session.
 
 
$subject_map is a reference to a hash. The keys of the hash are the id's of the subjects. The values of the hash are the  EPrint::Subject object relating to that id.
 
 
$reverse_map is a reference to a hash. Each key is the id of a subject. Each value is a reference to an array. The array contains a EPrints::DataObj::Subject objects, one for each child of the subject  with the id. The array is sorted by the labels for the subjects, in the current language.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_count_eprints -->==count_eprints==
 
 
  $count = $subject-&gt;count_eprints( $dataset )
 
 
Return the number of eprints in the dataset which are in this subject or one of its decendants. Search all fields of type subject.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_valid_id -->==valid_id==
 
 
  $boolean = EPrints::DataObj::Subject::valid_id( $id )
 
 
Return true if the string is an acceptable identifier for a subject.
 
 
This does not check all possible illegal values, yet.
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render -->==render==
 
 
  $subj-&gt;render()
 
 
undocumented
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_undocumented_methods -->=UNDOCUMENTED METHODS=
 
{{API:Undocumented Methods}}<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_create -->==create==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_create_from_data -->==create_from_data==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_defaults -->==get_defaults==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_local_name -->==local_name==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_posted_eprints -->==posted_eprints==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_description -->==render_description==
 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=_postamble_ --><!-- End of Pod2Wiki -->
 

Revision as of 15:40, 12 August 2009