The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
CatalystX-CRUD-0.46
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/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.

get_primary_key( context, pk_value )

Should return an array of the name of the field(s) to fetch() pk_value from and their respective values.

The default behaviour is to return primary_key and the corresponding value(s) from pk_value.

However, if you have other unique fields in your schema, you might return a unique field other than the primary key. This allows for a more flexible URI scheme.

A good example is Users. A User record might have a numerical id (uid) and a username, both of which are unique. So if username 'foobar' has a primary_key (uid) of '1234', both these URIs could fetch the same record:

 /uri/for/user/1234
 /uri/for/user/foobar

Again, the default behaviour is to return the primary_key field name(s) from config() (accessed via $self->primary_key) but you can override get_primary_key() in your subclass to provide more flexibility.

If your primary key is composed of multiple columns, your return value should include all those columns and their values as extracted from pk_value. Multiple values are assumed to be joined with ;;. See make_primary_key_string().

make_primary_key_string( object )

Using value of primary_string constructs a URI-ready string based on values in object. object is often the value of:

 $c->stash->{object}

but could be any object that has accessor methods with the same names as the field(s) specified by primary_key.

Multiple values are joined with ;; and any ; or / characters in the column values are URI-escaped.

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.

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

do_model( context, method, args )

Checks for presence of model_adapter() instance and calls method on either model() or model_adapter() as appropriate.

model_can( context, method_name )

Returns can() value from model_adapter() or model() as appropriate.

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