Krang::Category - a means to access information on categories


  use Krang::ClassLoader 'Category';
  # construct object
  my $category = Krang::Category->new(dir => 'category', # required
                                      parent_id => 1,
                                      site_id => 1);
  # 'parent_id' must be present for all categories except '/' 'site_id'
  # must be present for '/'
  # saves object to the DB
  # getters
  my $element   = $category->element();
  my $dir       = $category->dir();
  my $id        = $category->parent_id();
  my $parent    = $category->parent();
  my $id        = $category->site_id();
  my $site      = $category->site();
  my $may_see   = $category->may_see();
  my $may_edit  = $category->may_edit();
  my $id        = $category->category_id(); # undef until after save()
  my $id        = $category->element_id();  # undef until after save()
  my $url       = $category->url();         # undef until after save()
  # setters
  $category->dir( $some_single_level_dirname );
  # delete the category from the database
  # a hash of search parameters
  my %params =
  ( order_desc => 1,            # result ascend unless this flag is set
    limit => 5,                 # return 5 or less category objects
    offset => 1,                # start counting result from the
                                # second row
    order_by => 'url'           # sort on the 'url' field
    dir_like => '%bob%',        # match categories with dir LIKE '%bob%'
    parent_id => 8,
    site_id => 9,
    url_like => '%fred%' );
  # any valid object field can be appended with '_like' to perform a
  # case-insensitive sub-string match on that field in the database
  # returns an array of category objects matching criteria in %params
  my @categories = pkg('Category')->find( %params );


Categories serve three purposes in Krang. They serve as a means of dividing a sites content into distinct areas. Consequently, all content sharing the property of ``being chiefly about 'X''' should be placed within category 'X'. A category's dir, such as '/X', translates to both a relative system filepath for preview and publish output and a URL relative path. For example category '/X' would map to $site->publish_path() . '/X' as well as 'http://' . $site->url() . '/X'.

Secondly, categories serve as a data container. The 'element' field of a category object is a Krang::Element wherein arbitrary information about the category may be stored.

Thirdly, once a template object is associated with its element, a category serves to provide a layout container for story content that belongs to it. All of the fields defined in the category's element will be available to this template and may be used to derive category-specific layout behavior.

This module serves as a means of adding, deleting, and accessing these objects.

N.B. Categories must be associated with a site via the 'site_id' constructor arg or a 'parent_id' must be passed.



Access to fields for this object is provided my Krang::MethodMaker. The value of fields can be obtained and set in the following fashion:

 $value = $category->field_name();
 $category->field_name( $some_value );

The available fields for a category object are:



Krang, Krang::DB, Krang::Element