NAME

Bric::Util::Pref - Interface to Bricolage preferences.

VERSION

$Revision: 1.10 $

DATE

$Date: 2002/08/30 22:13:42 $

SYNOPSIS

use Bric::Util::Pref;

# Constructors.
my $pref = Bric::Util::Pref->new($init);
$pref = Bric::Util::Pref->lookup({ id => $id });
$pref = Bric::Util::Pref->lookup({ name => $name });
my @prefs = Bric::Util::Pref->list($params);

# Class Methods.
my @pref_ids = Bric::Util::Pref->list_ids($params);
my $meths = Bric::Util::Pref->my_meths;
my @meths = Bric::Util::Pref->my_meths(1);
# Fetch a value from the cache.
my $val = Bric::Util::Pref->lookup_val($name);

# Instance Methods
my $id = $pref->get_id;
my $name = $pref->get_name;
my $desc = $pref->get_description;
my $default = $pref->get_default;
my $val_name = $pref->get_val_name;

# Get a list of available value options.
my @opts = $pref->get_opts;
my $opts_ref = $pref->get_opts_href;

# Get and set the value.
my $value = $pref->get_value;
$pref = $pref->set_value($value);

# Save the pref.
$pref = $pref->save;

DESCRIPTION

This is the central interface for managing Bricolage application preferences. It should scale when we later decide to add user and user group preferences. Right now it'll just support those global application preferencest that we deem necessary for the application to work, such as Time Zone.

INTERFACE

Constructors

my $pref = Bric::Util::Pref->lookup({ id => $id })
my $pref = Bric::Util::Pref->lookup({ name => $name })

Looks up and instantiates a new Bric::Util::Pref object based on the Bric::Util::Pref object ID or name passed. If $id or $name is not found in the database, lookup() returns undef.

Throws:

Side Effects: If $id is found, populates the new Bric::Util::Pref object with data from the database before returning it.

Notes: NONE.

my (@prefs || $prefs_aref) = Bric::Util::Pref->list($params)

Returns a list or anonymous array of Bric::Util::Pref objects based on the search parameters passed via an anonymous hash. The supported lookup keys are:

Throws:

Side Effects: Populates each Bric::Util::Pref object with data from the database before returning them all.

Notes: NONE.

Destructors

$pref->DESTROY

Dummy method to prevent wasting time trying to AUTOLOAD DESTROY.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

Public Class Methods

my (@pref_ids || $pref_ids_aref) = Bric::Util::Pref->list_ids($params)

Returns a list or anonymous array of Bric::Util::Pref object IDs based on the search criteria passed via an anonymous hash. The supported lookup keys are the same as those for list().

Throws:

over 4

*

Unable to connect to database.

*

Unable to prepare SQL statement.

*

Unable to connect to database.

*

Unable to select column into arrayref.

*

Unable to execute SQL statement.

*

Unable to bind to columns to statement handle.

*

Unable to fetch row from statement handle.

Side Effects: NONE.

Notes: NONE.

my $val = Bric::Util::Pref->lookup_val($pref_name)

Looks up and returns the value of a preference without the expense of instantiating an object. Plus, it uses caching to keep it quick - the cache changes only when a value changes.

Throws:

Side Effects: See &$load_cache().

Notes: See &$load_cache().

$meths = Bric::Util::Pref->my_meths
(@meths || $meths_aref) = Bric::Util::Pref->my_meths(TRUE)

Returns an anonymous hash of instrospection data for this object. If called with a true argument, it will return an ordered list or anonymous array of intrspection data. The format for each introspection item introspection is as follows:

Each hash key is the name of a property or attribute of the object. The value for a hash key is another anonymous hash containing the following keys:

Public Instance Methods

my $id = $pref->get_id

Returns the ID of the Bric::Util::Pref object.

Throws:

Side Effects: NONE.

Notes: If the Bric::Util::Pref object has been instantiated via the new() constructor and has not yet been saved, the object will not yet have an ID, so this method call will return undef.

my $name = $pref->get_name

Returns preference name.

Throws:

Side Effects: NONE.

Notes: NONE.

my $description = $pref->get_description

Returns preference description.

Throws:

Side Effects: NONE.

Notes: NONE.

my $default = $pref->get_default

Returns preference default.

Throws:

Side Effects: NONE.

Notes: NONE.

my $value = $pref->get_value

Returns the preference value.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $pref->set_value($value)

Sets the preference value.

Throws:

Side Effects: NONE.

Notes: NONE.

my $val_name = $pref->get_val_name

Returns preference value's desriptive name. Note that if you've set the value, this method will return an incorrect value unless and until you instantiate the object again using lookup() or list().

Throws:

Side Effects: NONE.

Notes: NONE.

my (@opts || $opts_aref) = $pref->get_opts

Returns a list or anonymous array of options available for filling in the value of this preference.

Throws:

Side Effects: NONE.

Notes: NONE.

my $opts_href = $pref->get_opts_href

Returns a hasref of options available for filling in the value of this preference. The hash keys are the options, and the values are their descriptions.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $pref->save

Saves any changes to the Bric::Util::Pref object. Returns $self on success and undef on failure.

Throws:

Side Effects: NONE.

Notes: NONE.

PRIVATE

Private Class Methods

NONE.

Private Instance Methods

NONE.

Private Functions

my $pref_aref = &$get_em( $pkg, $params )
my $pref_ids_aref = &$get_em( $pkg, $params, 1 )

Function used by lookup() and list() to return a list of Bric::Util::Pref objects or, if called with an optional third argument, returns a listof Bric::Util::Pref object IDs (used by list_ids()).

Throws:

Side Effects: NONE.

Notes: NONE.

my $action = &$get_opts($self)

Queries this preference's value options from the database.

Throws:

Side Effects: NONE.

Notes: NONE.

$cache = &$load_cache()

Loads all the preference keys and values into a Cache::FileCache object.

Throws:

Side Effects: NONE.

Notes: Uses Bric::App::Cache for persistence across processes.

my $cache = &$cache_val($name, $value)

Sets a value in the cache.

Throws:

Side Effects: See &$load_cache().

Notes: See &$load_cache().

NOTES

NONE.

AUTHOR

David Wheeler <david@wheeler.net>

SEE ALSO

Bric

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 275:

=back doesn't take any parameters, but you said =back 4

Around line 353:

'=item' outside of any '=over'

Around line 628:

You forgot a '=back' before '=head2'

Around line 1055:

=back doesn't take any parameters, but you said =back 4