Bric::Biz::Keyword(3)

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

VITALS

Version
    $LastChangedRevision$

Date
    $LastChangedDate: 2005-08-19 20:36:47 +0200 (Fri, 19 Aug 2005) $

Subversion ID
    $Id: Keyword.pm 6566 2005-08-19 18:36:47Z theory $

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.