add_action (a code ref)

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.

edit_action (a code ref)

Called with:

    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.

delete_action (a code ref)

Called with:

    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.

form (a code ref)

Called with:

    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.

validator (a code ref)

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.

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:

    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.

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.

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.

redirect (optional, defaults to $your_self->location() )

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'
    

template (optional, defaults to form.tt)

The name of your form template.

text_descr

The text string used in the page titles and in the delete confirmation message.

use_clean_dates (optional, defaults to false)

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'>>.

turn_off_clean_params (optional, defaults to false)

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.