Gantry::Plugins::CRUD - helper for somewhat interesting CRUD work
use Gantry::Plugins::CRUD; my $user_crud = Gantry::Plugins::CRUD->new( add_action => \&user_insert, edit_action => \&user_update, delete_action => \&user_delete, form => \&user_form, validator => \&user_form_validator, redirect => \&redirect_function, template => 'your.tt', # defaults to form.tt text_descr => 'database row description', use_clean_dates => 1, turn_off_clean_params => 1, ); sub do_add { my ( $self ) = @_; $user_crud->add( $self, { data => \@_ } ); } sub user_insert { my ( $self, $form_params, $data ) = @_; # $data is the value of data from do_add my $row = My::Model->create( $params ); $row->dbi_commit(); } # Similarly for do_delete sub do_delete { my ( $self, $doomed_id, $confirm ) = @_; $user_crud->delete( $self, $confirm, { id => $doomed_id } ); } sub user_delete { my ( $self, $data ) = @_; my $doomed = My::Model->retrieve( $data->{id} ); $doomed->delete; My::Model->dbi_commit; }
This plugin helps you perform Create, Update, and Delete (commonly called CRUD, except that R is retrieve which you still have to implement separately).
Warning: most plugins export methods into your package, this one does NOT.
Normally, you can use Gantry::Plugins::AutoCRUD when you are controlling a single table. But, since its do_add, do_edit, and do_delete are genuine template methods*, sometimes it is not enough. For instance, if you need to allow a regular user and an admin edit for the same database table, you need two methods for each action (two for do_add, two for do_edit, and two for do_delete). This module can help.
Gantry::Plugins::AutoCRUD
* A template method has a series of steps. At each step, it calls a method via a hard coded name.
This module still does basically the same things that AutoCRUD does:
redirect to listing page if user presses cancel if form parameters are valid: callback to action method else: if method is POST: add form validation errors (re)display form
The following can be specified in your config to control the behavior of the plugin.
Specify form template to use by default. If nothing is specified it defaults to form.tt. If a template is specified during object creation it will override the value specified here.
This is an object oriented only module (it doesn't export like the other plugins).
Constructs a new CRUD helper. Pass in a list of the following callbacks and config parameters:
Called with:
your self object hash of form parameters the data you passed to add
Called only when the form parameters are valid. You should insert into the database and not die (unless the insert fails, then feel free to die). You don't need to change your location, but you may.
your self object hash of form parameters the data you passed to edit
Called only when form parameters are valid. You should update and not die (unless the update fails, then feel free to die). You don't need to change your location, but you may.
your self object the data you passed to delete
Called only when the user has confirmed that a row should be deleted. You should delete the corresponding row and not die (unless the delete fails, then feel free to die). You don't need to change your location, but you may.
your self object the data you passed to add or edit
This needs to return just like the _form method required by Gantry::Plugins::AutoCRUD. See its docs for details. The only difference between these is that the AutoCRUD calls _form with your self object and the row being edited (during editing) whereas this method ALWAYS receives both your self object and the data you supplied.
Optional.
By default, form parameters are validated with Data::FormValidator. Supply a validator callback to do your own thing. Your validator will be called with a hash reference, which will include the following named arguments:
self : your $self, params : $params, a hash ref of form paramters form : $form, profile: the form_profile of $form action : 'add' or 'edit'
Where $form is whatever your form callback returned, usually that is a hash reference for use by form.tt. It describes the form and its fields. See the form parameter to new directly above.
$form
The last parameter is the name of the method from this module making the callback. It can only be 'add' or 'edit.'
The form_profile (provided by Gantry::Utils::CRUDHelp) is a hash reference with three keys:
form_profile
required optional constraint_methods
required and optional are array references of field names. constraint_methods is a hash reference keyed by field name, storing a constraint. See Data::FormValidator for details on constraints.
required
optional
constraint_methods
What you do with those parameters is entirely up to you.
You must return:
an object which responds to the Data::FormValidator::Results API
You might find Gantry::Utils::FormErrors helpful, since it implements the required API for you.
But, if you want to implement your own, the objects must respond to:
has_missing has_invalid missing invalid
The methods prefixes with has_ return booleans. The return values for the other two depend on how they are called. If called with no arguments, they return the number of missing or invalid fields. If called with an argument, the argument is the name of a field. The method returns true if field is missing or invalid, false otherwise.
has_
Note that you may also set error_text in the form hash. This will also count as validation failure. Use this to get total control of how your errors are reported.
error_text
NOTE WELL: It is a bad idea to name your redirect callback 'redirect'. That name is used internally in Gantry.pm.
Where you want to go whenever an action is complete. If you need control on a per action basis end your action callback with:
$your_self->location( 'http://location.of/your/choice' );
Your redirect is called with:
your self object the data you passed to the add, edit, or delete the action: 'submit', 'submit_add_another' or 'cancel' the user request: 'add', 'edit' or 'delete'
The name of your form template.
The text string used in the page titles and in the delete confirmation message.
This is ignored unless you turn_off_clean_params, since it is redundant when clean_params is in use.
Make this true if you want your dates cleaned immediately before your add and edit callbacks are invoked.
Cleaning sets any false fields marked as dates in the form fields list to undef. This allows your ORM to correctly insert them as nulls instead of trying to insert them as blank strings (which is fatal, at least in PostgreSQL).
For this to work your form fields must have this key: <is = 'date'>>.
<is =
By default, right before an SQL insert or update, the params hash from the form is passed through the clean_params routine which sets all non-boolean fields which are false to undef. This prevents SQL errors with ORMs that can correctly translate blank strings into nulls for non-string types.
If you really don't want this routine, set turn_off_clean_params. If you turn it off, you can use_clean_dates, which only sets false dates to undef.
Note that in all cases the submit key is removed from the params hash by this module before any callback is made.
Call this in your do_add on a Gantry::Plugins::CRUD instance:
Gantry::Plugins::CRUD
sub do_special_add { my $self = shift; $crud_obj->add( $self, { data => \@_ } ); }
It will die unless you passed the following to the constructor:
add_action form
You may also pass redirect which must return a location suitable for passing to $your_self->relocate.
redirect
Call this in your do_edit on a Gantry::Plugins::CRUD instance:
sub do_special_edit { my $self = shift; my $id = shift; my $row = Data::Model->retrieve( $id ); $crud_obj->edit( $self, { id => $id, row => $row } ); }
edit_action form
Call this in your do_delete on a Gantry::Plugins::CRUD instance:
sub do_special_delete { my $self = shift; my $id = shift; my $confirm = shift; $crud_obj->delete( $self, $confirm, { id => $id } ); }
The $confirm argument is yes if the delete should go ahead and anything else otherwise. This allows our standard practice of having delete urls like this:
$confirm
http://somesite.example.com/item/delete/4
which leads to the confirmation form whose submit action is:
http://somesite.example.com/item/delete/4/yes
which is taken as confirmation.
delete_action
You can pick and choose which CRUD help you want from this module. It is designed to give you maximum flexibility, while doing the most repetative things in a reasonable way. It is perfectly good use of this module to have only one method which calls edit. On the other hand, you might have two methods that call edit on two different instances, two methods that call add on those same instances and a method that calls delete on one of the instances. Mix and match.
If you have a form field of type select_multiple, one of the form.tt keys is selected. It wants a sub ref so it can reselect items when the form fails to validate. This function will generate the proper sub ref (aka closure).
Parameters: form field name hash reference of default selections (usually the ones in the database)
Returns: a closure suitable for immediate use as the selected hash key value for a form field of type select_multiple.
Gantry::Plugins::AutoCRUD (for simpler situations) Gantry and the other Gantry::Plugins
Currently only one redirection can be defined. You can get more control by ending your action callback like this:
return $self->relocate( 'http://location.of/your/choice' );
Phil Crow <philcrow2000@yahoo.com>
Copyright (c) 2005, Phil Crow
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.
To install Gantry, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Gantry
CPAN shell
perl -MCPAN -e shell install Gantry
For more information on module installation, please visit the detailed CPAN module installation guide.