The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

MyLibrary::Facet

SYNOPSIS

        # require the necessary module
        use MyLibrary::Facet;

        # create a new Facet object
        my $facet = MyLibrary::Facet->new();

        # set attributes of facet object
        $facet->facet_name('Facet Name');
        $facet->facet_note('This is a facet note');

        # delete a facet note
        $facet->delete_facet_note();

        # commit facet to database
        $facet->commit();

        # delete facet from database
        $facet->delete();

        # get all facets
        my @facets = MyLibrary::Facet->get_facets();
        my @facets = MyLibrary::Facet->get_facets(sort => 'name');

        # get specific facets based on criteria
        my @facets = MyLibrary::Facet->get_facets(value => 'Discipline', field => 'name');

        # return related terms
        my @related_terms = $facet->related_terms();

        # return a sorted list of related terms
        my @related_terms = $facet->related_terms(sort => 'name');

DESCRIPTION

The purpose of this module is to manipulate MyLibrary Facet objects and perform database I/O against the facets table of a MyLibrary database. You may also retrieve a list of facet objects by using a special class method. A list of term ids with which a particular facet is associated can be retrieved as well and manipulated independently. All changes to either the facet descriptive data can be commited to the database.

METHODS

new()

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

        # create empty facet
        $facet = MyLibrary::Facet->new();

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

        # create a facet object using a known facet id
        $facet = MyLibrary::Facet->new(id => $id);

        # create a facet object using a known facet name
        $facet = MyLibrary::Facet->new(name => 'Disciplines');

facet_id()

This object method is used to retrieve the facet id of the current facet object. This method cannot be used to set the facet id.

        # get facet id
        my $facet_id = $facet->facet_id();

facet_name()

This is an attribute method which allows you to either get or set the name attribute of a facet. The names for facets will be created by the institutional team tasked with the responsibility of designating the broad categories under which resources will be categorized. To retrieve the name attribute:

        # get the facet name
        $facet->facet_name();

        # set the facet name
        $facet->facet_name('Format');

facet_note()

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

To retrieve the note attribute:

        # get the facet note
        $facet->facet_note();

        # set the facet note
        $facet->facet_note('The subject area under which a resource may be classified.');

delete_facet_note()

This object attribute method allows the removal of the facet note

        # delete the facet note
        $facet->delete_facet_note()

commit()

Use this method to commit the facet in memory to the database. Any updates made to facet attributes will be saved and new facets created will be saved. This method does not take any parameters.

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

A numeric code will be returned upon successfull completion of the operation. A return code of 1 indicates a successful commit. Otherwise, the method will cease program execution and die with an appropriate error message.

delete()

Use this method to remove a facet record from the database. The record will be deleted permanently.

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

get_facets()

This method can be used to retrieve a list of all of the facets currently in the database. Individual facet objects will be created and can be cycled through. This is a class method, not an object method. If the sort parameter is supplied, the list of facet ids will be sorted. Currently, the list can only be sorted by facet name. A specific list of facets can also be queried for by using the field and value parameters. Searchable fields are name and description. Examples are demonstrated below.

        # get all facets
        my @facets = MyLibrary::Facet->get_facets();

        # sort the returned list
        my @facets = MyLibrary::Facet->get_facets(sort => 'name');

        # find all facets based on criteria
        my @facets = MyLibrary::Facet->get_facets(value => 'Discpline', field => 'name');

This method should be used to return an array (a list) of term ids to which this facet is related. It requires no parameter input. If the facet is not related to any terms in the database, the method will return undef. The array of term ids can then be used to process the list of related terms. The returned list of term ids can also be sorted. This is an object method.

        # return related terms
        my @related_terms = $facet->related_terms();

        # return sorted list of related terms
        my @related_terms = $facet->related_terms(sort => 'name');

AUTHORS

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