Catalyst::Controller::Rose::CRUD(3)

NAME
Catalyst::Controller::Rose::CRUD - RDBO and RHTMLO for Catalyst CRUD apps

SYNOPSIS
 package MyApp::Controller::SomeCrud;

 use base 'Catalyst::Controller::Rose::CRUD';

 use MyApp::Forms::SomeCrud;

 sub form_class  { 'MyApp::Forms::SomeCrud' }
 sub init_form   { 'init_with_somecrud' }
 sub init_object { 'somecrud_from_form' }
 sub template    { 'path/to/somecrud/edit.xhtml' }
 sub model_name  { 'SomeCrud' }

 sub fetch : PathPart('cool/url/somecrud') Chained('/') CaptureArgs(1)
 {
    my ($self, $c, $id) = @_;
    $c->stash->{object_id} = $id;
    my @arg = $id ? (id => $id) : ();
    $c->stash->{object} = $c->model($self->model_name)->fetch(@arg);
    unless ($self->check_err($c) and $c->stash->{object})
    {
        $c->stash->{error} = 'No such Crud';
    }
 }

 1;

DESCRIPTION
This base controller is useful for creating scaffolding for your CRUD (Create, Read, Update, Delete) web applications.

It assumes you are using the Rose::DB::Object and Rose::HTML::Object modules or a subclass thereof.

Each controller assumes one form object = one db object.

Your subclass should define the following methods:

form_class
    The name of the HTML form object class.

init_form
    The name of the method in your HTML class that will initialize the HTML object.

init_object
    The name of the method in your HTML class that will initialize the RDBO object.

template
    The name of the default template to use for the form rendering.

fetch
    This is the most important method. fetch() defines the URL to which your controller will bind itself, how many arguments it expects before each action, and handles the retrieval of your DB object from the appropriate Model. See the SYNOPSIS for an example.

    You must set an 'object' key and an 'object_id' key in your stash() for the rest of the CRUD magic methods to work.

METHODS
The following methods are available:

  auto
The default auto() method will create a form object and stash() it under the "form" key. In order for that magic to work, you must override the form_class() method and then "use" the form class in your subclass.

Otherwise, you can override auto() in your subclass and do whatever you want to. However, all the other methods expect a form object under the "form" key in the stash().

  default
Doesn't do anything except satisfy the Catalyst namespace conventions. An error will be written to your log if anyone hits the URL that the default() method maps to (if any).

  create
Detachs to edit() with an id of 0.

  edit
Initializes the form with the db object.

  view
Does not do anything except satisfy the namespace. Your template can handle the rendering of a non-editable view of the db object, or you can override view() to handle it however you'd like.

  rm
Deletes the db row from the db.

 TODO: should redirect someplace safe to protect from browser re-load.

  save
Takes the form input, initializes the form object with it, validates the form, and then if the form is valid, initializes the db object, calls presave() and then saves the db object with save_obj().

If there are any validation errors, the stash->page->error value is set to the form object error() value and save() returns 0.

There's a lot going on in save(). Grok the code yourself to see what's what.

  precommit( context, object )
Callback method invoked by save() and rm() just before committing changes to the db.

If precommit() returns true (the default), the calling method will continue to commit. Otherwise, the method will abort and return 0.

precommit() is intended to be overridden in your subclass, in order to do any last-minute checks, hacks and fudges on the data you deem necessary.

  save_obj( context, object )
By default just calls the save() method on object. Override if you want to do anything you can't do in precommit().

  postcommit( context, object )
Called by save() and rm() after the db commit.

postcommit() is intended to be overridden in your subclass, although the default behaviour is sane.

  check_err( context )
Returns true if there are no errors in context, false if there are errors.

  can_read( context )

  can_write( context )
Authorization control with these two methods. The default is to return true (1) from both, for unlimited access. Override them to provide more fine-grained access.

Return true (1) to allow read or write. Return false (0) to deny access.

EXAMPLES
See the examples/ dir in the distribution.

SEE ALSO
Catalyst::Controller::Rose::Search Catalyst::Controller::Rose::EIP Catalyst::Controller::Rose::Autocomplete

AUTHOR
Peter Karman <perl@peknet.com>

Thanks to Atomic Learning, Inc for sponsoring the development of this module.

LICENSE
This library is free software. You may redistribute it and/or modify it under the same terms as Perl itself.