CatalystX::CRUD::Model(3)

NAME
CatalystX::CRUD::Model - base class for CRUD models

SYNOPSIS
 package MyApp::Model::Foo;
 use base qw( CatalystX::CRUD::Model );

 __PACKAGE__->config(
                    object_class    => 'MyApp::Foo',
                    page_size       => 50,
                    );

 # must define the following methods
 sub new_object         { }
 sub fetch              { }
 sub search             { }
 sub iterator           { }
 sub count              { }
 sub search_related     { }
 sub iterator_related   { }
 sub count_related      { }

 1;

DESCRIPTION
CatalystX::CRUD::Model provides a high-level API for writing Model classes. CatalystX::CRUD::Model methods typically return CatalystX::CRUD::Object objects.

This documentation is intended for Model developers.

CONFIGURATION
You may configure your CXCM-derived Models in the usual way (see the Catalyst Manual).

If the "object_class" key/value pair is set at initialization time, the value will be stored in the object_class() accessor. This feature is intended as a convenience for setting the name of the CatalystX::CRUD::Object class to which your CatalystX::CRUD::Model acts as an interface.

METHODS
CatalystX::CRUD::Model inherits from Catalyst::Component::ACCEPT_CONTEXT and Catalyst::Model. New and overridden methods are documented here.

  context
This accessor is available via Catalyst::Component::ACCEPT_CONTEXT and returns the $c value for the current request.

This method is not implemented at the CatalystX::CRUD::Model level but is highlighted here in order to remind developers that it exists.

  object_class
The object_class() accessor is defined for your convenience. It is set by the default Xsetup() method if a key called "object_class" is present in config() at initialization time.

  new
Overrides the Catalyst::Model new() method to call Xsetup().

  Xsetup
Called by new() at application startup time. Override this method in order to set up your model in whatever way you require.

Xsetup() is called by new(), which in turn is called by COMPONENT(). Keep that order in mind when overriding Xsetup(), notably that config() has already been merged by the time Xsetup() is called.

  page_size
Returns the "page_size" set in config().

  new_object
Returns CatalystX::CRUD::Object->new(). A sane default, assuming "object_class" is set in config(), is implemented in this base class.

REQUIRED METHODS
CXCM subclasses need to implement at least the following methods:

fetch( args )
    Should return the equivalent of CatalystX::CRUD::Object->new( args )->read().

search( query )
    Returns zero or more CXCO instances as an array or arrayref. query may be the return value of make_query().

iterator( query )
    Like search() but returns an iterator conforming to the CatalystX::CRUD::Iterator API.

count( query )
    Like search() but returns an integer.

search_related( obj, relationship )
    Returns zero or more CXCO instances like search(). The instances are related to obj via relationship.

iterator_related( obj, relationship )
    Like search_related() but returns an iterator.

count_related( obj, relationship )
    Like search_related() but returns an integer.

OPTIONAL METHODS
Catalyst components accessing CXCM instances may need to access model-specific logic without necessarily knowing what kind of model they are accessing. An example would be a Controller that wants to remain agnostic about the kind of data storage a particular model implements, but also needs to create a model-specific query based on request parameters.

 $c->model('Foo')->search(@arg);  # @arg depends upon what Foo is

To support this high level of abstraction, CXCM classes may implement the following optional methods.

make_query
    Should return appropriate values for passing to search(), iterator() and count(). Example of use:

     # in a CXCM subclass called MyApp::Model::Foo
     sub search {
         my $self = shift;
         my @arg  = @_;
         unless(@arg) {
             @arg = $self->make_query;
         }
         # search code here

         return $results;
     }

     sub make_query {
         my $self = shift;
         my $c    = $self->context;

         # use $c->req to get at params() etc.
         # and create a query

         return $query;
     }

     # elsewhere in a controller

     my $results = $c->model('Foo')->search;  # notice no @arg necessary since
                                              # it will default to
                                              # $c->model('Foo')->make_query()

add_related( obj, rel_name, foreign_value )
    Associate foreign object identified by foreign_value with obj via the relationship rel_name.

    It is up to the subclass to implement this method.

rm_related( obj, rel_name, foreign_value )
    Dissociate foreign object identified by foreign_value from obj via the relationship rel_name.

    It is up to the subclass to implement this method.

put_related( obj, rel_name, foreign_value )
    Create new related foreign object. Unlike add_related(), the foreign object need not already exist. put_related() should be idempotent.

remove_related
    remove_related() is an alias for rm_related().

find_related( obj, rel_name, foreign_value )
    Return related object for foreign_value based on rel_name for obj.

has_relationship( obj, rel_name )
    Should return true or false as to whether rel_name exists for obj.

    It is up to the subclass to implement this method.

AUTHOR
Peter Karman, "<perl at peknet.com>"

BUGS
Please report any bugs or feature requests to "bug-catalystx-crud at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CatalystX-CRUD>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT
You can find documentation for this module with the perldoc command.

    perldoc CatalystX::CRUD

You can also look for information at:

•   Mailing List

    <https://groups.google.com/forum/#!forum/catalystxcrud>

•   AnnoCPAN: Annotated CPAN documentation

    <http://annocpan.org/dist/CatalystX-CRUD>

•   CPAN Ratings

    <http://cpanratings.perl.org/d/CatalystX-CRUD>

•   RT: CPAN's request tracker

    <http://rt.cpan.org/NoAuth/Bugs.html?Dist=CatalystX-CRUD>

•   Search CPAN

    <http://search.cpan.org/dist/CatalystX-CRUD>

COPYRIGHT & LICENSE
Copyright 2007 Peter Karman, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.