Editing API:EPrints/DataObj/Subject

<!-- Pod2Wiki=_preamble_ 
This page has been automatically generated from the EPrints 3.4 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
 -->{{API}}{{Pod2Wiki}}{{API:Source|file=EPrints/DataObj/Subject.pm|package_name=EPrints::DataObj::Subject}}[[Category:API|SUBJECT]][[Category:API:EPrints/DataObj|SUBJECT]]<div><!-- Edit below this comment -->


<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
==NAME==
'''EPrints::DataObj::Subject''' - Subjects within a hierarchical tree.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_description -->
==DESCRIPTION==
This class represents a single node in the subjects tree. It also contains a number of methods for handling the entire tree.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_core_metadata_fields -->
==CORE METADATA FIELDS==
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_subjectid -->
===subjectid (id) ===

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_rev_number -->
===rev_number (int)===

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_name -->
===name (multilang)===

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_depositable -->
===depositable (boolean)===

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_sortvalue -->
===sortvalue (multilang)===

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_references_and_related_objects -->
==REFERENCES AND RELATED OBJECTS==
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_parents -->
===parents (id)===

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_ancestors -->
===ancestors (id)===

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_instance_variables -->
==INSTANCE VARIABLES==
See [[API:EPrints/DataObj#INSTANCE_VARIABLES|EPrints::DataObj]].

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_methods -->
==METHODS==
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_constructor_methods -->
===Constructor Methods===
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_new -->
====new====

 $subject = EPrints::DataObj::Subject-&gt;new( $session, $subjectid )
Create a new subject object with the ID <tt>$subjectid</tt>. The values for the subject are loaded from the database.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- 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.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_create -->
====create====

 $subject = EPrints::DataObj::Subject::create( $session, $id, $name, $parents, $depositable )
Creates a new subject in the database. <tt>$id</tt> is the ID of the  subject, <tt>$name</tt> is a multilang data structure with the name of the  subject in one or more languages. E.g.

 { en=&gt;"Trousers", en-us=&gt;"Pants" }
  
<tt>$parents</tt> is a reference to an array containing the ID of one or more  other subjects (don't make loops!). If <tt>$depositable</tt> is <tt>true</tt> then  data objects (typically eprints) may belong to this subject.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_create_from_data -->
====create_from_data====

 $dataobj = EPrints::DataObj::Subject-&gt;create_from_data( $session, $data, $dataset )
Returns <tt>undef</tt> if a bad (or no) <tt>subjectid</tt> is specified in <tt>$data</tt>.

Otherwise calls the parent method in [[API:EPrints/DataObj|EPrints::DataObj]].

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_class_methods -->
===Class Methods===
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_get_system_field_info -->
====get_system_field_info====

 $fields = EPrints::DataObj::Subject-&gt;get_system_field_info
Returns an array describing the system metadata of the subject  dataset.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_get_dataset_id -->
====get_dataset_id====

 $dataset = EPrints::DataObj::Subject-&gt;get_dataset_id
Returns the id of the [[API:EPrints/DataSet|EPrints::DataSet]] object to which this record  belongs.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_object_methods -->
===Object Methods===
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- 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 <tt>$force</tt> is set then always commit, even if there appear to be no changes.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_remove -->
====remove====

 $success = $subject-&gt;remove
Remove this subject from the database.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item__get_ancestors -->
====_get_ancestors====

 @subject_ids = $subject-&gt;_get_ancestors
Returns and array of all the ancestor subjects of this subject.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_top -->
====top====

 $subject = $subject-&gt;top
Returns the subject that is at the top of this subject's tree, which  may be the subject itself.

Returns <tt>undef</tt> if the subject is not part of a tree.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_create_child -->
====create_child====

 $child_subject = $subject-&gt;create_child( $id, $name, $depositable )
Similar to [[API:EPrints/DataObj/Subject#create|create]] but this creates a new subject as a child of  the current subject.

<tt>$id</tt> is the ID for the new child subject. <tt>$name</tt> is the label for  this new subject and <tt>$depositable</tt> is a boolean indicating whether  this new subject is depositable.

Returns the new child subject.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_get_children -->
====get_children====

 @children = $subject-&gt;get_children
Returns a list of subject data objects which are direct children of  the current subject.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_get_parents -->
====get_parents====

 @parents = $subject-&gt;get_parents
Returns a list of subject data objects which are direct parents of the  current subject.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_can_post -->
====can_post====

 $boolean = $subject-&gt;can_post( [ $user ] )
Determines whether the given <tt>$user</tt> if specified can post in this  subject.

Currently there is no way to configure subjects for certain users, so this just returns the <tt>true</tt> or <tt>false</tt> depending on the  <tt>depositable</tt> flag.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_render_with_path -->
====render_with_path====

 $xhtml = $subject-&gt;render_with_path( $session, $topsubjid )
Returns the XHTML DOM rendering name of this subject including it's  path from <tt>$topsubjid</tt>.

<tt>$topsubjid</tt> must be an ancestor of this subject.

E.g.

 Library of Congress &gt; B Somthing &gt; BC Somthing more Detailed
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- 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.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- 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" ]
 ]
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item__get_subjects2 -->
====_get_subjects2====

 $subjects = $subject-&gt;_get_subjects2( $postableonly, $hidenode, $nestids, $subjectmap, $rmap, $prefix )
Recursive function used by get_subjects.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_count_eprints -->
====count_eprints====

 $count = $subject-&gt;count_eprints( $dataset )
Returns the number of data objects in the dataset (typically eprints), which are in this subject or one of its decendants. Searches all  fields of type subject.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_render_description -->
====render_description====

 $subject-&gt;render_description
Returns a rendering describing the subject.

This is an alias for:

 $subject-&gt;render_value( "name" )
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_utility_methods -->
===Utility Methods===
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_remove_all -->
====remove_all====

 EPrints::DataObj::Subject::remove_all( $session )
Remove all subjects from the database. Use with care!

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- 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.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_valid_id -->
====valid_id====

 $boolean = EPrints::DataObj::Subject::valid_id( $id )
Returns <tt>true</tt> if the string <tt>$id</tt> is an acceptable identifier for a  subject.

This does not check all possible illegal values, just that it has no  whitespace.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_deprecated_methods -->
===Deprecated Methods===
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_posted_eprints -->
====posted_eprints====

 @eprints = $subject-&gt;posted_eprints( $dataset )
DEPRECATED

This method is no longer used by EPrints, and may be removed in a later release.

Returns all the data objects in the <tt>$dataset</tt>, (typically, <tt>eprint</tt> or its virtual datasets, such as <tt>archive</tt>, <tt>buffer</tt> and <tt>inbox</tt>, which are in this subject (or below it in the tree, its children, etc.). It searches all fields of type <tt>subject</tt>.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_render -->
====render====

 $subj-&gt;render
DEPRECATED

Subjects cannot be rendered. Use [[API:EPrints/DataObj/Subject#render_description|render_description]] instead.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_see_also -->
==SEE ALSO==
[[API:EPrints/DataObj|EPrints::DataObj]] and [[API:EPrints/DataSet|EPrints::DataSet]].

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_copyright -->
==COPYRIGHT==
{{API:Copyright}}
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment -->