The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Handel::Base - Base class for Cart/Order/Item classes

SYNOPSIS

    use MyCustomCart;
    use strict;
    use warnings;
    use base qw/Handel::Base/;
    
    __PACKAGE__->item_class('MyCustomCart::Item');
    
    __PACKAGE__->storage({
        schema_source  => 'Carts',
        constraints    => {
            id         => {'Check Id'      => \&constraint_uuid},
            shopper    => {'Check Shopper' => \&constraint_uuid},
            type       => {'Check Type'    => \&constraint_cart_type},
            name       => {'Check Name'    => \&constraint_cart_name}
        },
        default_values => {
            id         => __PACKAGE__->storage_class->can('new_uuid'),
            type       => CART_TYPE_TEMP
        }
    });
    __PACKAGE__->create_accessors;
    
    1;

DESCRIPTION

Handel::Base is a base class for the Cart/Order/Item classes that glues those classes to a Handel::Storage object.

METHODS

accessor_map

Returns a hashref containing the column/accessor mapping used when create_accessors was last called. This is used by get_column/set_column to get the accessor name for any given column.

    $schema->add_column('foo' => {accessor => 'bar');
    ...
    $base->create_accessors;
    $base->bar('newval');  # calls $base->set_column('foo', 'newval');
    ...
    sub set_column {
        my ($self, $column, $value) = @_;
        my $accessor = $self->accessor_map->{$column} || $column;
        
        $self->result->$accessor($value);
    };

cart_class

Arguments: $cart_class

Gets/sets the cart class to be used when creating orders from carts.

    __PACKAGE__->cart_class('CustomCart');

A Handel::Exception exception will be thrown if the specified class can not be loaded.

checkout_class

Arguments: $checkout_class

Gets/sets the checkout class to be used to process the order through the CHECKOUT_PHASE_INITIALIZE phase when creating a new order and the process options is set. The default checkout class is Handel::Checkout.

    __PACKAGE__->checkout_class('CustomCheckout');

A Handel::Exception exception will be thrown if the specified class can not be loaded.

create_accessors

Creates a column accessor for each accessor returned from "column_accessors" in Handel::Storage. If you have defined columns in your schema to have an accessor that is different than the column name, that will be used instead of the column name.

    package CustomCart;
    use strict;
    use warnings;
    use base qw/Handel::Cart/;
    __PACKAGE__->storage->add_columns('foo');
    __PACKAGE__->create_accessors;

Each accessor will call get_column/set_column, passing the real database column name.

create_instance

Arguments: $result

Creates a new instance of the current class, stores the resultset result object inside, and does any configuration on the new object before returning it.

    my $result = $storage->create({name => 'My Cart'});
    my $cart = Handel::Cart->create_instance($result);

This is used internally by inflate_result and storage. There's probably no good reason to use this yourself.

A Handel::Exception exception will be thrown if this method is called on an object. It is a class method only.

get_column

Arguments: $column

Returns the value for the specified column from the current result. If an accessor has been defined for the column in accessor_map, that will be used against the result instead.

    my $cart = Handel::Cart->create({name => 'My Cart'});
    print $cart->get_column('name');

A Handel::Exception::Argument exception will be thrown if no column is specified.

A Handel::Exception exception will be thrown if this method is called on an class. It is an object method only.

has_storage

Returns true if the current class has an instance of Handel::Storage. Returns undef if it does not.

    package CustomCart;
    use strict;
    use warnings;
    use base qw/Handel::Cart/;
    if (!__PACKAGE__->has_storage) {
        __PACKAGE->init_storage;
    };

inflate_result

Arguments: $result

This method is called by Handel::Iterator to inflate objects returned by various iterator operations into the current class. There is probably no good reason to use this method yourself.

init_storage

Initializes the storage object in the current class, cloning it from the superclass if necessary.

    package CustomCart;
    use strict;
    use warnings;
    use base qw/Handel::Cart/;
    if (!__PACKAGE__->has_storage) {
        __PACKAGE->init_storage;
    };

item_class

Arguments: $item_class

Gets/sets the item class to be used when returning cart/order items.

    __PACKAGE__->item_class('CustomCartItem');

The class specified should be a subclass of Handel::Base, or at least provide its create_instance and result methods.

A Handel::Exception exception will be thrown if the specified class can not be loaded.

set_column

Arguments: $column, $value

Sets the value for the specified column on the current result. If an accessor has been defined for the column in accessor_map, that will be used against the result instead.

    my $cart = Handel::Cart->create({name => 'My Cart'});
    $cart->set_column('name', 'New Cart');

If autoupdate is enable for the current object, set_column will call update automatically. If autoupdate is disabled, be sure to call update to save change to the database.

    my $cart = Handel::Cart->create({name => 'My Cart'});
    $cart->set_column('name', 'New Cart');
    if (!$cart->autoupdate) {
        $cart->update;
    };

A Handel::Exception::Argument exception will be thrown if no column is specified.

A Handel::Exception exception will be thrown if this method is called on an class. It is an object method only.

storage

Arguments: \%options

Returns the local instance of storage_class. If a local object doesn't exist, it will create and return a new one*. If specified, options will be passed to setup on the storage object.

* When creating subclasses of Cart/Order/Item classes and no storage object exists in the current class, storage will attempt to clone one from the immediate superclass using init_storage and clone first before creating a new instance. However, a clone will only be created if it is of the same type specified in storage_class.

    package CustomCart;
    use strict;
    use warnings;
    use base qw/Handel::Cart/;
    
    my $storage = __PACKAGE__->storage;
    ## clones a new storage object from Handel::Cart

storage_class

Arguments: $storage_class

Gets/sets the default storage class to be created by init_storage.

    __PACKAGE__->storage_class('MyStorage');
    
    print ref __PACKAGE__->storage; # MyStorage

If you are using a custom storage class, you must set storage_class before you call storage for the first time in this class.

A Handel::Exception::Storage exception will be thrown if the specified class can not be loaded.

result

Returns the schema resultset result object for the current class object. There should be no need currently to access this directly unless you are writing custom subclasses.

    my @columns = $cart->result->columns;

See DBIx::Class::ResultSet and DBIx::Class::Row for more information on using the result object.

update

Arguments: \%data

Sends all of the column updates to the database. If autoupdate is off in the current object, you must call this to save your changes or they will be lost when the object goes out of scope.

    $cart->name('My Cart');
    $cart->description('My Favorite Cart');
    $cart->update;

You may also pass a hash reference containing name/value pairs to be applied:

    $cart->update({
        name        => 'My Cart',
        description => 'My Favorite Cart'
    });

Be careful to always use the column name, not its accessor alias if it has one.

get_component_class

Arguments: $name

Gets the current class for the specified component name.

    my $class = $self->get_component_class('item_class');

There is no good reason to use this. Use the specific class accessors instead.

set_component_class

Arguments: $name, $value

Sets the current class for the specified component name.

    $self->set_component_class('item_class', 'MyItemClass');

A Handel::Exception exception will be thrown if the specified class can not be loaded.

There is no good reason to use this. Use the specific class accessors instead.

SEE ALSO

Handel::Storage, DBIx::Class::ResultSet, DBIx::Class::Row

AUTHOR

    Christopher H. Laco
    CPAN ID: CLACO
    claco@chrislaco.com
    http://today.icantfocus.com/blog/