Peter Karman


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


    # create a controller
    package MyApp::Controller::Foo;
    use strict;
    use base qw( CatalystX::CRUD::Controller );
        form_class              => 'MyForm::Foo',
        init_form               => 'init_with_foo',
        init_object             => 'foo_from_form',
        default_template        => 'path/to/foo/',
        model_name              => 'Foo',
        model_adapter           => 'FooAdapter', # optional
        model_meta              => { moniker => 'SomeTable' },  # optional
        primary_key             => 'id',
        view_on_single_result   => 0,
        page_size               => 50,
        allow_GET_writes        => 0,
        naked_results           => 0,
    # 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/<pk>/<relname>/<pk2>/add
    #  foo/<pk>/<relname>/<pk2>/rm
    #  foo/create
    #  foo/list
    #  foo/search


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.


See the SYNOPSIS section.

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


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.


Attribute: Private

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


Attribute: Private

The fallback method. The default returns a 404 error.

fetch( primary_key )

Attribute: chained to namespace, expecting one argument.

Calls do_model fetch() 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 fetch() is saved in stash() as object.

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


Attribute: Local

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

If the Form class has a 'field_value' method, create() will pre-populate the Form instance and Object instance with param-based values (i.e. seeds the form via request params).


 # form and object will have name set to 'bar'

NOTE: This is a GET method named for consistency with the C in CRUD. It is not equivalent to a POST in REST terminology.


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

Checks the can_read() 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.


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().


Alias for view(), just for consistency with the R in CRUD.


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 POST requests to /save. If found, save() will detach() to rm().

save() returns 0 on any error, and returns 1 on success.


Alias for save(), just for consistency with the U in CRUD.


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

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

Calls the delete() method on the object.


Wrapper for rm(), just for consistency with the D in CRUD.


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().


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.

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

Similar to fetch(), a chain base method for add_related() and rm_related(). Expects two arguments: rel_name and foreign_pk_value. Those two values are put in stash under those key names.

Note that related() has a PathPart of '' so it does not appear in your URL:


will resolve in the action_for add().


Attribute: chained to related().

Dissociate a related many-to-many object of relationship name rel_name with primary key value foreign_pk_value.



will remove user 123 from the group 456.

Sets the 204 (enacted, no content) HTTP response status on success.


Attribute: chained to related().

Associate the primary object retrieved in fetch() with the object with foreign_pk_value via a related many-to-many relationship rel_name.



will add user 123 to the group 456.

Sets the 204 (enacted, no content) HTTP response status on success.

Attribute: chained to fetch() like related() is.

Attribute: chained to fetch_related().

Returns list of related objects.



will return groups related to user 123.

Attribute: chained to related().

Returns list of related objects based on foreign key value.



will return groups of pk 456 related to user 123.


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

new( c, args )

Sets up the controller instance, detecting and instantiating the model_adapter if set in config().


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.


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.

If form_to_object() returns 0, save() will abort at that point in the process, so form_to_object() should set whatever template and other stash() values should be used in the response.

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 (or model_adapter()), 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().

uri_for_view_on_single_result( context, results )

Returns 0 unless view_on_single_result returns true.

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

make_query( context, arg )

This is an optional method. If implemented, do_search() will call this method and pass the return value on to the appropriate model methods. If not implemented, the model will be tested for a make_query() method and it will be called instead.

Either the controller subclass or the model must implement a make_query() method.

do_search( context, arg )

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

Results are saved in stash() under the results key.

If naked_results is true, then results are set just as they are returned from search() or list() (directly from the Model).

If naked_results is false (default), then results is a CatalystX::CRUD::Results object.


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


primary_key may be a single column name or an array ref of multiple column names.



Peter Karman, <perl at>


Please report any bugs or feature requests to bug-catalystx-crud at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


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

    perldoc CatalystX::CRUD

You can also look for information at:


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


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.