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

From EPrints Documentation
Jump to: navigation, search
 
(7 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
<!-- Pod2Wiki=_preamble_  
 
<!-- Pod2Wiki=_preamble_  
−
This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
+
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]][[Category:API:EPrints/DataObj/Subject|SUBJECT]]<div><!-- Edit below this comment -->
+
  -->{{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 -->
 
<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
 
==NAME==
 
==NAME==
−
'''EPrints::DataObj::Subject''' - Class and methods relating to the subejcts tree.
+
'''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%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 17: Line 17:
 
<!-- Pod2Wiki=head_description -->
 
<!-- Pod2Wiki=head_description -->
 
==DESCRIPTION==
 
==DESCRIPTION==
−
This class represents a single node in the subejcts tree. It also contains a number of methods for handling the entire tree.
+
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 -->
  
−
EPrints::DataObj::Subject is a subclass of EPrints::DataObj
+
 
 +
<!-- 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%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 28: Line 114:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
−
<!-- Pod2Wiki=item_get_system_field_info -->
+
<!-- Pod2Wiki=head_instance_variables -->
−
===$thing = EPrints::DataObj::Subject-&gt;get_system_field_info===
+
==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 -->
  
−
Return an array describing the system metadata of the Subject dataset.
 
  
 +
<!-- 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%; '>
 
<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>
 
<span style='display:none'>User Comments</span>
Line 41: Line 144:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_new -->
 
<!-- Pod2Wiki=item_new -->
−
===$subject = EPrints::DataObj::Subject-&gt;new( $session, $subjectid )===
+
====new====
  
−
Create a new subject object given the id of the subject. The values for the subject are loaded from the database.
+
$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%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 53: Line 157:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_new_from_data -->
 
<!-- Pod2Wiki=item_new_from_data -->
−
===$subject = EPrints::DataObj::Subject-&gt;new_from_data( $session, $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.
 
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%; '>
 
<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>
 
<span style='display:none'>User Comments</span>
Line 65: Line 246:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_commit -->
 
<!-- Pod2Wiki=item_commit -->
−
===$success = $subject-&gt;commit( [$force] )===
+
====commit====
  
 +
$success = $subject-&gt;commit( [ $force ] )
 
Commit this subject to the database, but only if any fields have  changed since we loaded it.
 
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.
+
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%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 79: Line 261:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_remove -->
 
<!-- Pod2Wiki=item_remove -->
−
===$success = $subject-&gt;remove===
+
====remove====
  
 +
$success = $subject-&gt;remove
 
Remove this subject from the database.
 
Remove this subject from the database.
  
Line 90: Line 273:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
−
<!-- Pod2Wiki=item_get_dataset_id -->
+
<!-- Pod2Wiki=item__get_ancestors -->
−
===$dataset = EPrints::DataObj::Subject-&gt;get_dataset_id===
+
====_get_ancestors====
  
−
Returns the id of the [[API:EPrints/DataSet|EPrints::DataSet]] object to which this record belongs.
+
@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%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 102: Line 286:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
−
<!-- Pod2Wiki=item_remove_all -->
+
<!-- Pod2Wiki=item_top -->
−
===EPrints::DataObj::Subject::remove_all( $session )===
+
====top====
  
−
Static function.
+
$subject = $subject-&gt;top
 +
Returns the subject that is at the top of this subject's tree, which  may be the subject itself.
  
−
Remove all subjects from the database. Use with care!
+
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%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 117: Line 302:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_create_child -->
 
<!-- Pod2Wiki=item_create_child -->
−
===$child_subject = $subject-&gt;create_child( $id, $name, $depositable )===
+
====create_child====
  
−
Similar to EPrints::DataObj::Subject::create, but this creates the new subject as a child of the current subject.
+
$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%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 129: Line 319:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_children -->
 
<!-- Pod2Wiki=item_get_children -->
−
===@children = $subject-&gt;get_children===
+
====get_children====
  
−
Return a list of EPrints::DataObj::Subject objects which are direct children of the current subject.
+
@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%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 141: Line 332:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_parents -->
 
<!-- Pod2Wiki=item_get_parents -->
−
===@parents = $subject-&gt;get_parents===
+
====get_parents====
  
−
Return a list of EPrints::DataObj::Subject objects which are direct parents of the current subject.
+
@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%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 153: Line 345:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_can_post -->
 
<!-- Pod2Wiki=item_can_post -->
−
===$boolean = $subject-&gt;can_post( [$user] )===
+
====can_post====
  
−
Determines whether the given user can post in this subject.
+
$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 true or false depending on the "depositable" flag.
+
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%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 167: Line 360:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_render_with_path -->
 
<!-- Pod2Wiki=item_render_with_path -->
−
===$xhtml = $subject-&gt;render_with_path( $session, $topsubjid )===
+
====render_with_path====
  
−
Return the name of this subject including it's path from $topsubjid.
+
$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>.
  
−
$topsubjid must be an ancestor of this subject.
+
<tt>$topsubjid</tt> must be an ancestor of this subject.
  
−
eg.  
+
E.g.
−
 
 
−
Library of Congress &gt; B Somthing &gt; BC Somthing more Detailed
 
  
 +
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%; '>
 
<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>
 
<span style='display:none'>User Comments</span>
Line 185: Line 379:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_paths -->
 
<!-- Pod2Wiki=item_get_paths -->
−
===@paths = $subject-&gt;get_paths( $session, $topsubjid )===
+
====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.
 
This function returns all the paths from this subject back up to the specified top subject.
  
Line 199: Line 394:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_subjects -->
 
<!-- Pod2Wiki=item_get_subjects -->
−
===$subject_pairs = $subject-&gt;get_subjects ( [$postable_only], [$show_top_level], [$nes_tids], [$no_nest_label] )===
+
====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.  
 
Return a reference to an array. Each item in the array is a two  element list.  
  
Line 232: Line 428:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
−
<!-- Pod2Wiki=item_subject_label -->
+
<!-- Pod2Wiki=item__get_subjects2 -->
−
===$label = EPrints::DataObj::Subject::subject_label( $session, $subject_id )===
+
====_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 -->
  
−
Return the full label of a subject, including parents. Returns undef if the subject id is invalid.
 
  
−
The returned string is encoded in utf8.
+
<!-- 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%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 247: Line 494:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_all -->
 
<!-- Pod2Wiki=item_get_all -->
−
===( $subject_map, $reverse_map ) = EPrints::DataObj::Subject::get_all( $session )===
+
====get_all====
  
 +
( $subject_map, $reverse_map ) = EPrints::DataObj::Subject::get_all( $session )
 
Get all the subjects for the current archvive of $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.
+
$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.
+
$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%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 262: Line 510:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
−
<!-- Pod2Wiki=item_count_eprints -->
+
<!-- Pod2Wiki=item_valid_id -->
−
===$count = $subject-&gt;count_eprints( $dataset )===
+
====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.
  
−
Return the number of eprints in the dataset which are in this subject or one of its decendants. Search all fields of type 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%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 274: Line 525:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
−
<!-- Pod2Wiki=item_valid_id -->
+
<!-- Pod2Wiki=head_deprecated_methods -->
−
===$boolean = EPrints::DataObj::Subject::valid_id( $id )===
+
===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
  
−
Return true if the string is an acceptable identifier for a subject.
+
This method is no longer used by EPrints, and may be removed in a later release.
  
−
This does not check all possible illegal values, yet.
+
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%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 289: Line 552:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_render -->
 
<!-- Pod2Wiki=item_render -->
−
===$subj-&gt;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 -->
 +
 
  
−
undocumented
+
<!-- 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%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 302: Line 579:
 
<!-- Pod2Wiki=head_copyright -->
 
<!-- Pod2Wiki=head_copyright -->
 
==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%; '>
 
<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>
 
<span style='display:none'>User Comments</span>

Latest revision as of 18:43, 10 January 2022

EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects

API: Core API

Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki


NAME

EPrints::DataObj::Subject - Subjects within a hierarchical tree.

User Comments


DESCRIPTION

This class represents a single node in the subjects tree. It also contains a number of methods for handling the entire tree.

User Comments


CORE METADATA FIELDS

User Comments


subjectid (id)

User Comments


rev_number (int)

User Comments


name (multilang)

User Comments


depositable (boolean)

User Comments


sortvalue (multilang)

User Comments


REFERENCES AND RELATED OBJECTS

User Comments


parents (id)

User Comments


ancestors (id)

User Comments


INSTANCE VARIABLES

See EPrints::DataObj.

User Comments


METHODS

User Comments


Constructor Methods

User Comments


new

$subject = EPrints::DataObj::Subject->new( $session, $subjectid )

Create a new subject object with the ID $subjectid. The values for the subject are loaded from the database.

User Comments


new_from_data

$subject = EPrints::DataObj::Subject->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.

User Comments


create

$subject = EPrints::DataObj::Subject::create( $session, $id, $name, $parents, $depositable )

Creates a new subject in the database. $id is the ID of the subject, $name is a multilang data structure with the name of the subject in one or more languages. E.g. 

{ en=>"Trousers", en-us=>"Pants" }

$parents is a reference to an array containing the ID of one or more other subjects (don't make loops!). If $depositable is true then data objects (typically eprints) may belong to this subject.

User Comments


create_from_data

$dataobj = EPrints::DataObj::Subject->create_from_data( $session, $data, $dataset )

Returns undef if a bad (or no) subjectid is specified in $data.

Otherwise calls the parent method in EPrints::DataObj.

User Comments


Class Methods

User Comments


get_system_field_info

$fields = EPrints::DataObj::Subject->get_system_field_info

Returns an array describing the system metadata of the subject dataset.

User Comments


get_dataset_id

$dataset = EPrints::DataObj::Subject->get_dataset_id

Returns the id of the EPrints::DataSet object to which this record belongs.

User Comments


Object Methods

User Comments


commit

$success = $subject->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.

User Comments


remove

$success = $subject->remove

Remove this subject from the database.

User Comments


_get_ancestors

@subject_ids = $subject->_get_ancestors

Returns and array of all the ancestor subjects of this subject.

User Comments


top

$subject = $subject->top

Returns the subject that is at the top of this subject's tree, which may be the subject itself.

Returns undef if the subject is not part of a tree.

User Comments


create_child

$child_subject = $subject->create_child( $id, $name, $depositable )

Similar to create but this creates a new subject as a child of the current subject.

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

Returns the new child subject.

User Comments


get_children

@children = $subject->get_children

Returns a list of subject data objects which are direct children of the current subject.

User Comments


get_parents

@parents = $subject->get_parents

Returns a list of subject data objects which are direct parents of the current subject.

User Comments


can_post

$boolean = $subject->can_post( [ $user ] )

Determines whether the given $user if specified 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.

User Comments


render_with_path

$xhtml = $subject->render_with_path( $session, $topsubjid )

Returns the XHTML DOM rendering name of this subject including it's path from $topsubjid.

$topsubjid must be an ancestor of this subject.

E.g. 

Library of Congress > B Somthing > BC Somthing more Detailed

User Comments


get_paths

@paths = $subject->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.

User Comments


get_subjects

$subject_pairs = $subject->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" ]
]

User Comments


_get_subjects2

$subjects = $subject->_get_subjects2( $postableonly, $hidenode, $nestids, $subjectmap, $rmap, $prefix )

Recursive function used by get_subjects.

User Comments


count_eprints

$count = $subject->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.

User Comments


render_description

$subject->render_description

Returns a rendering describing the subject.

This is an alias for: 

$subject->render_value( "name" )

User Comments


Utility Methods

User Comments


remove_all

EPrints::DataObj::Subject::remove_all( $session )

Remove all subjects from the database. Use with care!

User Comments


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.

User Comments


valid_id

$boolean = EPrints::DataObj::Subject::valid_id( $id )

Returns true if the string $id is an acceptable identifier for a subject.

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

User Comments


Deprecated Methods

User Comments


posted_eprints

@eprints = $subject->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 $dataset, (typically, eprint or its virtual datasets, such as archive, buffer and inbox, which are in this subject (or below it in the tree, its children, etc.). It searches all fields of type subject.

User Comments


render

$subj->render

DEPRECATED

Subjects cannot be rendered. Use render_description instead.

User Comments


SEE ALSO

EPrints::DataObj and EPrints::DataSet.

User Comments


COPYRIGHT

© Copyright 2000-2024 University of Southampton.

EPrints 3.4 is supplied by EPrints Services.

http://www.eprints.org/eprints-3.4/

LICENSE

This file is part of EPrints 3.4 http://www.eprints.org/.

EPrints 3.4 and this file are released under the terms of the GNU Lesser General Public License version 3 as published by the Free Software Foundation unless otherwise stated.

EPrints 3.4 is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with EPrints 3.4. If not, see http://www.gnu.org/licenses/.

User Comments


Retrieved from ‘https://wiki.eprints.org/w/index.php?title=API:EPrints/DataObj/Subject&oldid=14169’