The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
CatalystX-CRUD-0.17
River stage one • 8 direct dependents • 8 total dependents
1 ++
/ CatalystX::CRUD::Controller

NAME

CatalystX::CRUD::Controller - base class for CRUD controllers

SYNOPSIS

    # create a controller
    package MyApp::Controller::Foo;
    use strict;
    use base qw( CatalystX::CRUD::Controller );
    
    __PACKAGE__->config(
                    form_class              => 'MyForm::Foo',
                    init_form               => 'init_with_foo',
                    init_object             => 'foo_from_form',
                    default_template        => 'path/to/foo/edit.tt',
                    model_name              => 'Foo',
                    primary_key             => 'id',
                    view_on_single_result   => 0,
                    page_size               => 50,
                    );
                    
    1;
    
    # now you can manage Foo objects using your MyForm::Foo form class
    # with URIs at:
    #  foo/<pk>/edit
    #  foo/<pk>/view
    #  foo/<pk>/save
    #  foo/<pk>/rm
    #  foo/create
    #  foo/list
    #  foo/search

DESCRIPTION

CatalystX::CRUD::Controller is a base class for writing controllers that play nicely with the CatalystX::CRUD::Model API. The basic controller API is based on Catalyst::Controller::Rose::CRUD and Catalyst::Controller::Rose::Search.

See CatalystX::CRUD::Controller::RHTMLO for one implementation.

CONFIGURATION

See the SYNOPSIS section.

The configuration values are used extensively in the methods described below and are noted in bold where they are used.

URI METHODS

The following methods are either public via the default URI namespace or (as with auto() and fetch()) are called via the dispatch chain. See the SYNOPSIS.

auto

Attribute: Private

Calls the form() method and saves the return value in stash() as form.

default

Attribute: Private

The fallback method. The default is simply to write a warning to the Catalyst log() method.

fetch( primary_key )

Attribute: chained to namespace, expecting one argument.

Calls model_name read() method with a single key/value pair, using the primary_key config value as the key and the primary_key as the value.

The return value of read() is saved in stash() as object.

The primary_key value is saved in stash() as object_id.

create

Attribute: Local

Namespace for creating a new object. Forwards to fetch() and edit() with a primary_key value of 0 (zero).

edit

Attribute: chained to fetch(), expecting no arguments.

Checks the can_write() and has_errors() methods before proceeding.

Populates the form in stash() with the object in stash(), using the init_form method. Sets the template value in stash() to default_template.

view

Attribute: chained to fetch(), expecting no arguments.

Checks the can_read() and has_errors() methods before proceeding.

Acts the same as edit() but does not set template value in stash().

save

Attribute: chained to fetch(), expecting no arguments.

Creates an object with form_to_object(), then follows the precommit(), save_obj() and postcommit() logic.

See the save_obj(), precommit() and postcommit() hook methods for ways to affect the behaviour of save().

The special param() value _delete is checked to support REST-like behaviour. If found, save() will detach() to rm().

rm

Attribute: chained to fetch(), expecting no arguments.

Checks the can_write() and has_errors() methods before proceeeding.

Calls the delete() method on the object.

list

Attribute: Local

Display all the objects represented by model_name(). The same as calling search() with no params(). See do_search().

Attribute: Local

Query the model and return results. See do_search().

count

Attribute: Local

Like search() but does not set result values, only a total count. Useful for AJAX-y types of situations where you want to query for a total number of matches and create a pager but not actually retrieve any data.

INTERNAL METHODS

The following methods are not visible via the URI namespace but directly affect the dispatch chain.

form

Returns an instance of config->{form_class}. A single form object is instantiated and cached in the controller object. If the form object has a clear or reset method it will be called before returning.

field_names

Returns an array ref of the field names in form(). By default just calls the field_names() method on the form(). Your subclass should implement this method if your form class does not have a field_names() method.

can_read( context )

Returns true if the current request is authorized to read() the object in stash().

Default is true.

can_write( context )

Returns true if the current request is authorized to create() or update() the object in stash().

form_to_object( context )

Should return an object ready to be handed to save_obj(). This is the primary method to override in your subclass, since it will handle all the form validation and population of the object.

Will throw_error() if not overridden.

See CatalystX::CRUD::Controller::RHTMLO for an example.

save_obj( context, object )

Calls the update() or create() method on the object, picking the method based on whether object_id in stash() evaluates true (update) or false (create).

precommit( context, object )

Called by save(). If precommit() returns a false value, save() is aborted. If precommit() returns a true value, save_obj() gets called.

The default return is true.

postcommit( context, object )

Called in save() after save_obj(). The default behaviour is to issue an external redirect resolving to view().

view_on_single_result( context, results )

Returns 0 unless the config() key of the same name is true.

Otherwise, calls the primary_key() value on the first object in results and constructs a uri_for() value to the edit() action in the same class as the current action.

do_search( context, arg )

Prepare and execute a search. Called internally by list() and search().

CONVENIENCE METHODS

The following methods simply return the config() value of the same name.

form_class
init_form
init_object
model_name
default_template
primary_key
page_size

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:

ACKNOWLEDGEMENTS

This module based on Catalyst::Controller::Rose::CRUD by the same author.

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.