API:EPrints/DataObj/Subject
EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects
Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki
Contents
NAME
EPrints::DataObj::Subject - Subjects within a hierarchical tree.
DESCRIPTION
This class represents a single node in the subjects tree. It also contains a number of methods for handling the entire tree.
CORE METADATA FIELDS
subjectid (id)
rev_number (int)
name (multilang)
depositable (boolean)
sortvalue (multilang)
REFERENCES AND RELATED OBJECTS
parents (id)
ancestors (id)
INSTANCE VARIABLES
See EPrints::DataObj.
METHODS
Constructor Methods
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.
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.
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.
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.
Class Methods
get_system_field_info
$fields = EPrints::DataObj::Subject->get_system_field_info
Returns an array describing the system metadata of the subject dataset.
get_dataset_id
$dataset = EPrints::DataObj::Subject->get_dataset_id
Returns the id of the EPrints::DataSet object to which this record belongs.
Object Methods
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.
remove
$success = $subject->remove
Remove this subject from the database.
_get_ancestors
@subject_ids = $subject->_get_ancestors
Returns and array of all the ancestor subjects of this subject.
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.
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.
get_children
@children = $subject->get_children
Returns a list of subject data objects which are direct children of the current subject.
get_parents
@parents = $subject->get_parents
Returns a list of subject data objects which are direct parents of the current subject.
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.
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
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.
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" ] ]
_get_subjects2
$subjects = $subject->_get_subjects2( $postableonly, $hidenode, $nestids, $subjectmap, $rmap, $prefix )
Recursive function used by get_subjects.
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.
render_description
$subject->render_description
Returns a rendering describing the subject.
This is an alias for:
$subject->render_value( "name" )
Utility Methods
remove_all
EPrints::DataObj::Subject::remove_all( $session )
Remove all subjects from the database. Use with care!
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.
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.
Deprecated Methods
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.
render
$subj->render
DEPRECATED
Subjects cannot be rendered. Use render_description instead.
SEE ALSO
EPrints::DataObj and EPrints::DataSet.
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/.
