NAME

Class::AlzaboWrapper - Higher level wrapper around Alzabo Row and Table objects

SYNOPSIS

use Class::AlzaboWrapper ( table => $schema->table('User') );

DESCRIPTION

This module is intended for use as a base class when you are writing a class that wraps Alzabo's table and row classes.

USAGE

Our usage examples will assume that there is database containing tables named "User" and "UserComment", and that the subclass we are creating is called WebTalk::User.

Exceptions

This module throws exceptions when invalid parameters are given to methods. The exceptions it throws are objects which inherit from Exception::Class::Base, just as with Alzabo itself.

Import

When a subclass imports this module, it should pass a "table" parameter to it, which should be an Alzabo::Runtime::Table object. This is considered the "main table" being wrapped by the given subclass, though it can of course access other tables freely.

So for our hypothetical WebTalk::User class, we would pass the "User" table when importing Class::AlzaboWrapper.

When importing the module, you can also pass a "skip" method, which should be an array reference. This reference contains the names of columns for which methods should not be auto-generated. See the Generated methods section below for more details.

When you import the module, it will make sure that your class is declared as a subclass of Class::AlzaboWrapper automatically.

If invalid parameters are given when importing the module, it will throw a Class::AlzaboWrapper::Exception::Params exception.

Inherited methods

Subclasses inherit a number of method from Class::AlzaboWrapper.

Class methods

• new

  The new() method provided allows you to create new objects either from an Alzabo row object, or from the main table's primary keys.

  This method first looks to see if the parameters it was given match the table's primary key. If they do, it attempts to create an object using those parameters. If no primary key values are given, then it looks for an parameter called "object", which should be an Alzabo::Runtime::Row object.

  Finally, if your subclass defines a _new_row() method, then this will be called, with all the parameters provided to the new() method. This allows you to create new objects based on other parameters.

  If your subclass defines an _init() method, then this will be called after the object is created, before it is returned from the new() method to the caller.

  If invalid parameters are given then this method will throw a Class::AlzaboWrapper::Exception::Params exception.

• create

  This method is used to create a new object and insert it into the database. It simply calls the insert() method on the class's associated table object. Any parameters given to this method are passed given to the insert() method as its "values" parameter.

• potential

  This creates a new object based on a potential row, as opposed to one in the database. Similar to the create() method, any parameters passed are given to the table's potential_row() method as the "values" parameter.

• columns

  This is simply a shortcut to the associated table's columns method. This may also be called as an object method.

• column

  This is simply a shortcut to the associated table's column method. This may also be called as an object method.

• table

  This methods returns the Alzbao table object associated with the subclass. This may also be called as an object method.

• cursor ($cursor)

  Given an Alzabo::Runtime::Cursor object (either a row or join cursor), this method returns a new Class::AlzaboWrapper::Cursor object.

Object methods

• row_object

  This method returns the Alzabo::Runtime::Row object associated with the given subclass object. So, for our hypothetical WebTalk::User class, this would return an object representing the underlying row from the User table.

• select / update / delete / is_live

  These methods are simply passthroughs to the underlying Alzabo row's methods of the same names. You may want to subclass some of these in order to change their behavior.

Generated methods

For each column in the associated table, their is a method created that selects that column's value from the underlying row for an object. For example, if our User table contained "username" and "email" columns, then our WebTalk::User object would have username() and email() methods generated.

As was mentioned before, if a column is listed in the "skip" parameter when this module is imported, this method will not be made.

Class::AlzaboWrapper methods

The Class::AlzaboWrapper module has a method it provides:

• table_to_class ($table)

  Given an Alzabo table object, this method returns its associated subclass.

Cursors

When using this module, you need to use the Class::AlzaboWrapper::Cursor module to wrap Alzabo's cursor objects, so that objects the cursor returns are of the appropriate subclass, not plain Alzabo::Runtime::Row objects.

Subclassing

If you want to subclass this module, you may want to override the import() method in order to do something like create methods in the calling class. If you do this, you should call Class::AlzaboWrapper's import() method as well. You'll need to override the "base" and "caller" parameters when doing this. Set "base" to your subclass and "caller" to the class that called your import method. Here is an example:

package My::AlzaboWrapper;

use base 'Class::AlzaboWrapper';

sub import
{
    my $class = shift;

    # called via use base
    return unless @_;

    my %p = @_;

    my $caller = (caller(0))[0];

    $class->SUPER::import( %p,
                           base   => $class,
                           caller => $caller,
                         );

    $class->_make_more_methods(%p);
}

SUPPORT

The Alzabo docs are conveniently located online at http://www.alzabo.org/docs/.

There is also a mailing list. You can sign up at http://lists.sourceforge.net/lists/listinfo/alzabo-general.

Please don't email me directly. Use the list instead so others can see your questions.

SEE ALSO

The Regional Vegetarian Guide at http://www.regveg.org/ is a site I created which actually uses this code as part of the application. Its source is available from the web site.

COPYRIGHT

Copyright (c) 2002-2003 David Rolsky. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

AUTHOR

Dave Rolsky, <autarch@urth.org>