Name

Bric::Biz::Keyword - Interface to Bricolage Keyword Objects

Synopsis

use Bric::Biz::Keyword;

 # Constructors.
 my $keyword = Bric::Biz::Keyword->new($init);
 $keyword = Bric::Biz::Keyword->lookup({ id => $id });
 my @keywords = Bric::Biz::Keyword->list($params);

 # Class Methods.
 my @keyword_ids = Bric::Biz::Keyword->list_ids($params);
 my $keywords_href = Bric::Biz::Keyword->href($params);
 my $meths = Bric::Biz::Keyword->my_meths;

 # Instance methods.
 $id = $keyword->get_id;
 my $name = $keyword->get_name;
 $keyword = $keyword->set_name($name)
 my $screen_name = $keyword->get_screen_name;
 $keyword = $keyword->set_screen_name($screen_name)
 my $sort_name = $keyword->get_sort_name;
 $keyword = $keyword->set_sort_name($sort_name)

 $keyword = $keyword->activate;
 $keyword = $keyword->deactivate;
 $keyword = $keyword->is_active;

 # Save the changes to the database
 $keyword = $keyword->save;

Description

The Keyword module allows assets to be characterized by a set of topical keywords. These keywords can be used to group assets or during a search on a particular topic.

Interface

Constructors

new

my $keyword = Bric::Biz::Keyword->new;
$keyword = Bric::Biz::Keyword->new($init);

Constructs a new keyword object and returns it. An anonymous hash of initial values may be passed. The supported keys for that hash references are:

name

The name of this keyword.

screen_name

The way this name should be displayed on screen (ie name='George', screen name='George Washington'). If not specified name will be used for screen_name.

sort_name

The word used to sort keywords. If not specified then name will be used for sort_name.

The name and domain_name attributes must be globally unique or an exception will be thrown.

Throws:

Exception::DA
Error::NotUnique

lookup

my $keyword = Bric::Biz::Keyword->lookup({ id => $id });
$keyword = Bric::Biz::Keyword->lookup({ name => $name });

Looks up and constructs an existing keyword object in the database and returns it. A Keyword ID or name name can be used as the keyword object unique identifier to look up. If no keyword object is found in the database, then lookup() will return undef.

Throws:

Exception::DA

list

my @keywords = Bric::Biz::Keyword->list($params);
my $keywords_aref = Bric::Biz::Keyword->list($params);

Returns a list or anonymous array of keyword objects based on the search parameters passed via an anonymous hash. The supported lookup keys that may use valid SQL wild card characters are:

name
screen_name
sort_name

The ANY() operator may be used to specify a list of values for any of these parameters.

The supported lookup keys that must be an exact value are:

id

Keyword ID. May use ANY for a list of possible values.

active

A boolean value indicating if the keyword is active.

grp_id

A Bric::Util::Grp::Keyword object ID. May use ANY for a list of possible values.

object

Returns all keywords for a given object - may be a Bric::Biz::Category, Bric::Biz::Asset::Business::Media or a Bric::Biz::Asset::Business::Story object. May use ANY for a list of possible values.

Throws:

Exception::DA

href

my $keywords_href = Bric::Biz::Keyword->href($params);

Returns an anonymous hash of keyword objects based on the search parameters passed via an anonymous hash. The hash keys will be the keyword IDs, and the values will be the corresponding keywords. The supported lookup keys are the same as those for list().

Throws:

Exception::DA

Class Methods

list_ids

my @keyword_ids = Bric::Biz::Keyword->list_ids($params);
my $keyword_ids_aref = Bric::Biz::Keyword->list_ids($params);

Returns a list or anonymous array of keyword object IDs based on the search parameters passed via an anonymous hash. The supported lookup keys are the same as for the list() method.

Throws:

Exception::DA

my_meths

my $meths = Bric::Biz::Keyword->my_meths
my @meths = Bric::Biz::Keyword->my_meths(1);
my $meths_aref = Bric::Biz::Keyword->my_meths(1);
@meths = Bric::Biz::Keyword->my_meths(0, 1);
$meths_aref = Bric::Biz::Keyword->my_meths(0, 1);

Returns Bric::Biz::Keyword attribute accessor introspection data. See Bric for complete documtation of the format of that data. Returns accessor introspection data for the following attributes:

name

The keyword name. A unique identifier attribute.

screen_name

The keyword display name.

sort_name

The keyword sort name.

active

The keyword's active status boolean.

Accessors

id

my $id = $keyword->get_id;

Returns the keyword object's unique database ID.

name

my $name = $keyword->get_name;
$keyword = $keyword->set_name($name);

Get and set the keyword object's unique name. The value of this attribute must be case-insensitively globally unique. If a non-unique value is passed to set_name(), an exception will be thrown.

Side Effects: The <screen_name> and sort_name attributes will be set to the same value as the name attribute if they are not yet defined.

Throws:

Error::NotUnique
Error::Undef

screen_name

my $screen_name = $keyword->get_screen_name;
$keyword = $keyword->set_screen_name($screen_name);

Get and set the keyword object's screen_name.

sort_name

my $sort_name = $keyword->get_sort_name;
$keyword = $keyword->set_sort_name($sort_name);

Get and set the keyword object's sort_name.

active

$keyword = $keyword->activate;
$keyword = $keyword->deactivate;
$keyword = $keyword->is_active;

Get and set the keyword object's active status. activate() and deactivate() each return the keyword object. is_active() returns the keyword object when the keyword is active, and undef when it is not.

Note: The old remove(), get_state() set_state(), get_active(), and set_active() methods have been deprecated. Please use is_active(), activate(), and deactivate() instead.

Instance Methods

save

$keyword = $keyword->save;

Saves any changes to the keyword object to the database. Returns the keyword object on success and throws an exception on failure.

Thows:

Error::Undef
Exception::DA

Authors

Garth Webb <garth@perijove.com>

Sam Tregar <stregar@about-inc.com>

David Wheeler <david@kineticode.com>

See Also

Bric::Biz::Asset::Business

Business assets, including stories and media, can be associated with keywords.

Bric::Biz::Category

Categories can be associated with key words.

Copyright and License

Copyright (c) 2001 About.com. Changes Copyright (c) 2002-2003 Kineticode, Inc. and others. See Bric::License for complete license terms and conditions.