NAME

SYNOPSIS

    use Gantry::Plugins::AjaxCRUD;

    my $user_crud = Gantry::Plugins::AjaxCRUD->new(
        add_action      => \&user_insert,
        edit_action     => \&user_update,
        delete_action   => \&user_delete,
        form            => \&user_form,
        setup_action    => \&user_setup,
        cancel_action   => \&user_cancel,
        success_action  => \&user_success,
        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;
    }

    sub user_success {
        my $self = shift;

        $self->do_main( @_ );
    }

    sub user_cancel {
        my $self = shift;

        $self->do_main( @_ );
    }

    sub user_setup {
        my ( $self, $data, $action, $text_descr ) = @_;

        $self->template_wrapper('nowrapper.tt');
        $self->stash->view->template('form.tt');

        $self->stash->view->title('Add' . $text_descr)
                if ($action eq 'add');
        $self->stash->view->title('Edit' . $text_descr)
                if ($action eq 'edit');
        $self->stash->view->title('Delete' . $text_descr)
                if ($action eq 'delete');

    }

DESCRIPTION

For those who don't know, CRUD is short for CReate, Update, and Delete. (Some people include retrieve in this list, but users of Perl ORMs can use those for retrievals.) While AJAX stands for Asynchronous JavaScript and XML. With varying emphasis on the XML part.

What this all means, is that your application is now being driven from the browser and not from the server. So a differant style of CRUD needs to be used.

Notice: most plugins export methods into your package, this one does NOT.

This module differs from "Gantry::Plugins::AutoCRUD" in the same ways that "Gantry::Plugins::CRUD" does. It differs from "Gantry::Plugins::CRUD" in how it responds to requests. This module exists to support AJAX forms. As such, it does not do anything which might cause a page refresh by the browser.

This module still does basically the same things that CRUD does:

    redispatch 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

And as such is an almost drop in replace for CRUD.

METHODS

new

Constructs a new AjaxCRUD helper. Pass in a list of the following callbacks and config parameters (similar, but not the same as in CRUD):

add

Call this in your do_add on a "Gantry::Plugins::AjaxCRUD" instance:

    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
    

edit

Call this in your do_edit on a "Gantry::Plugins::AjaxCRUD" 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 } );
    }
    

It will die unless you passed the following to the constructor:

        edit_action
        form
    

delete

Call this in your do_delete on a "Gantry::Plugins::AjaxCRUD" 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:

    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.

It will die unless you passed the following to the constructor:

        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.

HELPER FUNCTIONS

select_multiple_closure

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.

SEE ALSO

 Gantry::Plugins::CRUD (for the same approach with page refreshes)

 Gantry::Plugins::AutoCRUD (for simpler situations)

 Gantry and the other Gantry::Plugins

AUTHOR

COPYRIGHT and LICENSE

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.