Peter Karman > CatalystX-CRUD-0.55 > CatalystX::CRUD::Controller

Download:
CatalystX-CRUD-0.55.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.55   Source   Latest Release: CatalystX-CRUD-0.56

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

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.

fetch_related

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

list_related

Attribute: chained to fetch_related().

Returns list of related objects.

Example:

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

will return groups related to user 123.

view_related

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.

syntax highlighting: