CatalystX::CRUD::Controller(3)

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:

•   Mailing List

    <https://groups.google.com/forum/#!forum/catalystxcrud>

•   AnnoCPAN: Annotated CPAN documentation

    <http://annocpan.org/dist/CatalystX-CRUD>

•   CPAN Ratings

    <http://cpanratings.perl.org/d/CatalystX-CRUD>

•   RT: CPAN's request tracker

    <http://rt.cpan.org/NoAuth/Bugs.html?Dist=CatalystX-CRUD>

•   Search CPAN

    <http://search.cpan.org/dist/CatalystX-CRUD>

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.