The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
CatalystX-CRUD-0.55
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',
        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,
    );
                    
    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/<pk>/<relname>/<pk2>/add
    #  foo/<pk>/<relname>/<pk2>/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 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.

create

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

Example:

 http://localhost/foo/create?name=bar
 # 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.

edit

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.

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

read

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

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

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

update

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

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.

delete

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

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.

related( rel_name, foreign_pk_value )

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:

 http://yourhost/foo/123/bars/456/add

will resolve in the action_for add().

remove

Attribute: chained to related().

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

Example:

 http://yoururl/user/123/group/456/remove

will remove user 123 from the group 456.

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

add

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.

Example:

 http://yoururl/user/123/group/456/add

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.

Example:

 http://yoururl/user/123/group/list

will return groups related to user 123.

Attribute: chained to related().

Returns list of related objects based on foreign key value.

Example:

 http://yoururl/user/123/group/456/view

will return groups of pk 456 related to user 123.

INTERNAL METHODS

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

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.

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.

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

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

page_size
allow_GET_writes
naked_results

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.