The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
MyLibrary-3.0.4
River stage zero No dependents
++
/ MyLibrary::Term

NAME

MyLibrary::Term

SYNOPSIS

        # require the necessary module
        use MyLibrary::Term;

        # create a new Term object
        my $term = MyLibrary::Term->new();

        # set the attributes of a Term object
        $term->term_name('Term One');
        $term->term_note('Sample note for a term');
        $term->facet_id(9999);

        # delete the term note
        $term->delete_term_note();

        # commit Term data to database
        $term->commit();

        # get a list of all term objects
        my @terms = MyLibrary::Term->get_terms();

        # get list of term objects based on criteria
        my @terms = MyLibrary::Term->get_terms(field => 'name', value => 'Chemistry');

        # get a list of all related resource ids
        my @related_resources = $term->related_resources();

        # delete relations between terms and resources
        my @related_resources = $term->related_resources(del => [@resource_ids]);

        # set new relations between a term and resources
        my @related_resources = $term->related_resources(new => [@resource_ids]);       

        # sort a list of returned resource ids according to name
        my @related_resources = $term->related_resources(sort => 'name');

        # get a list of all related suggested resource ids
        my @suggested_resources = $term->suggested_resources();

        # retrieve a sorted list of related suggested resource ids
        my @suggested_resources = $term->suggested_resources(sort => 'name');

        # return a list of related librarian objects
        my @librarians = $term->librarians();

        # return a list of related librarian ids
        my @librarians = $term->librarians(output => 'id');

        # add a list of librarians to this term, dismissing database relational integrity
        $term->librarians(new => [@librarian_ids], strict => 'off');

        # sort a list of supplied term ids according to specific criteria
        my @sorted_terms = MyLibrary::Term->sort(term_ids => [@term_ids], type => 'name');

        # return overlapping resources with this term (~30 term ids max)
        my @overlap_resources = $term->overlap(term_ids => [@term_ids]);

        # return a distinct set of related terms within a resource group
        my @distinct_terms = MyLibrary::Term->distinct_terms(resource_ids => [@resource_ids]);

        # delete a list of librarians from this term
        $term->librarians(del => [@librarians_ids]);

        # delete a Term object from the database
        $term->delete();

DESCRIPTION

Use this module to get and set the terms used to classify things in a MyLibrary database. You can also retrieve a list of all term objects in the database, as well as get, set or delete relations between term objects and resource objects.

METHODS

new()

This method creates a new term object. Called with no input, this constructor will return a new, empty term object:

        # create empty term object
        my $term = MyLibrary::Term->new();

The constructor can also be called using a known term id or term name:

        # create a term object using a known term id
        my $term = MyLibrary::Term->new(id => $id);

        # create a term object using a known term name
        my $term = MyLibrary::Term->new(name => $name);

term_id()

This method can be used to retrieve the term id for the current term object. It cannot be used to set the id for the term.

        # get term id
        my $term_id = $term->term_id();

term_name()

This is an attribute method which allows you to either get or set the name attribute of a term. The names for terms will be created by the institutional team tasked with the responsibility of designating the more specific categories under which resources will be categorized. A term is related to one and only one parent facet. To retrieve the name attribute:

        # get the term name
        my $term_name = $term->term_name();

term_note()

This method allows one to either retrieve or set the term descriptive note.

        # get the term note
        my $term_note = $term->term_note();

        # set the term note
        $term->term_note('This is a term note.');

delete_term_note()

Use this method to delete the term note

        # delete term note
        $term->delete_term_note();

facet_id()

This method may be used to either set or retrieve the value of the related facet id for this term. When the term is commited to the database, if the facet id is changed, the relation between this term and the facets will also be changed.

        # get the related facet id
        my $related_facet_id = $term->facet_id();

        # set the related facet id
        $term->facet_id(25);

commit()

This object method is used to commit the current term object in memory to the database. If the term already exists in the database, it will be updated. New terms will be inserted into the database.

        # commit the term
        $term->commit();

delete()

This object method should be used with caution as it will delete an existing term from the database. Any associations with the Resources will also be deleted with this method in order to maintain referential integrity. If an attempt is made to delete a term which does not yet exist in the database, a return value of '0' will result. A successful deletion will result in a return value of '1'.

        # delete the term
        $term->delete();

get_terms()

This class method can be used to retrieve an array of all term objects. The array can then be used to sequentially process through all of the existing terms. This method can also be used to retrieve a list of objects based on object attributes such as name or description. This can be accomplished by supplying the field and value parameters to the method. Examples are demonstrated below.

        # get all the terms
        my @terms = MyLibrary::Term->get_terms();

        # get all terms based on criteria
        my @terms = MyLibrary::Term->get_terms(field => 'name', value => 'Biology and Life Sciences');

This object method can be used to retrieve an array (a list) of resource ids to which this term is related. This list can then be used to sequentially process through all related resources (for example in creating a list of related resources). No parameters are necessary for this method to retrieve related resources, however, new relatetions can be created by supplying a list of resource ids using the 'new' parameter. If the term is already related to a supplied resource id, that resource id will simply be discarded. Upon a term commit (e.g. $term->commit()), the new relations with resources will be created. Also, the input must be in the form of numeric digits. Care must be taken because false relationships could be created. A list of the currently related resources will always be returned (if such relations exist).

        # get all related resources
        my @related_resources = $term->related_resources();

        # supply new related resources
        $term->related_resources(new => [10, 12, 14]);
        or
        my @new_related_resource_list = $term->related_resources(new => [@new_resources]);

The method will by default check to make sure that the new resources to which this term should be related exist in the database. This feature may be switched off by supplying the strict => 'off' parameter. Changing this parameter to 'off' will switch off the default behavior and allow bogus resource relations to be created.

        # supply new related resources with relational integrity switched off
        $term->related_resources(new => [10, 12, 14], strict => 'off');

Resources which do not exist in the database will simply be rejected if strict relational integrity is turned on.

The method can also be used to delete a relationship between a term and a resource. This can be accomplished by supplying a list of resources via the 'del' parameter. The methodology is the same as the 'new' parameter with the primary difference being that referential integrity will be assumed (for example, that the resource being severed already exists in the database). This will not delete the resource itself, it will simply delete the relationship between the current term object and the list of resources supplied with the 'del' parameter.

        # sever the relationship between this term and a list of resource ids
        $term->related_resources(del => [10, 11, 12]);

        or

        $term->related_resources(del => [@list_to_be_severed]);

If the list includes resources to which the current term is not related, those resource ids will simply be ignored. Priority will be given to resource associations added to the object; deletions will occur during the commit() after new associations have been created.

Finally, a returned list of related resources can be sorted.

        # sort a returned list of resource ids according to resource name
        my @related_resources = $term->related_resources(sort => 'name');

suggested_resources()

This is an object method which can be used to retrieve, set or delete suggested resource relationships between terms and resources. The return set will always be an array of resource ids which can then be used to process through the resources to which the ids correspond. This method functions similarly to the related_resource() method and uses similar parameters to change method functionality. If no parameters are submitted, the method simply returns a list of resource_ids or undef if there are no suggested resources for this term. As with the related_resources() method, passing a sort parameter will sort the returned list according to the parameter value. Currently, only 'name' is acceptable as a parameter value.

        # get all suggested resources
        my @suggested_resources = $term->suggested_resources();

        # get a sorted list of suggested resources
        my @suggested_resources = $term->suggested_resources(sort => 'name');

        # supply new suggested resources
        my @new_suggested_resource_list = $term->suggested_resources(new => [@new_suggested_resource_list]);

As with related_resources(), this method will by default check to make sure that the new resources to which this term should be related exist in the database. The strict => 'off' parameter may also be supplied to the method to turn off relational integrity checks.

        # turn off relational integrity checks
        $term->suggested_resources(new => [@new_suggested_resources], strict => 'off');

Turning off this feature will allow for bogus relations to be created.

The parameter to delete suggested resource relationships is del => [@set_to_delete]. The list supplied will be automatically deleted when the term is commited with commit(). This parameter does not delete the resources themselves, only their relationship as a 'suggested resource'. If the list includes resource ids to which the term is not related, they will simply be discarded and ignored.

        # remove suggested resource relationships
        $term->suggested_resources(del => [@list_to_be_deleted]);

Priority for processing the list will be given to resources associations added to the term, but the overall effect on the data should be transparent.

librarians()

This object method will return a list of related librarian objects/ids or undef if no librarians are associated with this term. The type of data returned is controlled by the 'output' parameter. If 'id' is chosen as the preferred output, a simple list of related librarian ids will be returned. If the output type of 'object' is preferred, the returned librarian object can be manipulated using the librarian object methods. This method can also be used to add or delete librarian associations with this term. The 'new' and 'del' parameters exist for this purpose (see examples below). A list of librarian ids should be provied for these parameters. Relational integrity can be abandoned by using the 'strict' parameter and giving it a value of off.

        # return a list of librarian objects
        my @librarians = $term->librarians();

        # return a list of librarian ids
        my @librarians = $term->librarians(output => 'id');

        # add a list of librarian associations to this term
        $term->librarians(new => [@librarian_ids]);
        $term->librarians(new => [@librarian_ids], strict => 'off');

        # remove a list of librarian associations from this term
        $term->librarians(del => [@librarian_ids]);

sort()

This class method performs a simple sort on a supplied list of term ids according to specific criteria, which is indicated as a parameter value for the method.

        # sort term ids by term name
        my @sorted_terms = MyLibrary::Term->sort(term_ids => [@term_ids], type => 'name');

overlap()

This object method returns a list of overlapping resources with a provided list of term ids. If there are no overlapping resources, the method returns null. If submitted term ids do not exist in the database, the method will ignore that input. Since some databases are limited by how many table joins they can perform in one query, limit the number of term ids to approximately 25-30 at a time. Otherwise, the method will likely fail.

        # return overlapping resources with this term
        my @overlap_resources = $term->overlap(term_ids => [@term_ids]);

distinct_terms()

This class method returns a unique list of term ids (which can be sorted using the sort() method) that correspond to a specific group of resource ids.

        # return a distinct set of related terms within a resource group
        my @distinct_terms = MyLibrary::Term->distinct_terms(resource_ids => [@resource_ids]);

AUTHORS

Eric Lease Morgan <emorgan@nd.edu> Robert Fox <rfox2@nd.edu>