Gantry::Plugins::AjaxCRUD - helper for AJAX based CRUD work

Gantry documentation Contained in the Gantry distribution.

Index

Code Index:

NAME

Top

Gantry::Plugins::AjaxCRUD - helper for AJAX based CRUD work

SYNOPSIS

Top

    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

Top

This module is very similar to Gantry::Plugins::CRUD, but it is aimed at AJAX based systems. Therefore, it resists all urges to refresh the page. This leads to three extra callbacks as shown in the summary above and discussed below.

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

Top

This is an object oriented only module (it doesn't export like the other plugins). It has many of the same methods as Gantry::Plugins::CRUD plus three extras.

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_action (a code ref)

Same as in CRUD.

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)

Same as in CRUD.

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)

Same as in CRUD.

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)

Same as in CRUD.

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.

setup_action (a code ref)

Called with:

    your self object
    the data you passed to add, edit or deltet
    the desired action (add, edit or delete)
    the text description

This method is called immediately by add_action, edit_action, and delete_action to set the forms title and template. The default action for CRUD is to use form.tt as the template and to wrap your form with the site template. Using the site wrapper will cause a page reload. By exposing this default, you can change how this is handled.

In the above example this is done by calling $self->template_wrapper() with the template nowrapper.tt. What nowrapper.tt needs to do, depends on which AJAX toolkit is being used on the browser. But it could be just as simple as the following:

    [% content %]

At this point your form is now just a HTML fragment.

Another example, lets say that your boss has just returned from the latest Web Developer conference and is all aglow with the possibilites of an AJAX front end. He has deemed that all forms should be rendered on the client side and JSON will be used to send the form parameters. What to do? Well CPAN to the rescue. Install the TT filter for JSON, along with the JSON.pm module. Now create a template named json.tt like this:

    [% USE JSON %]
    [% view.data.json %]

Change the froms template from form.tt to json.tt and add the following statement:

    $self->content_type('application/json');

You are now sending your form as a JSON datastream.

cancel_action (a code ref)

Called with:

    your self object
    the data you passed to add, edit or deltet
    the action (add, edit or delete)
    the user request

Triggered by the user successfully submitting the form. This and success_action replaces the redirect callback used by Gantry::Plugins::CRUD. They should redispatch directly to a do_* method like this:

    sub _my_cancel_action {
        my $self = shift;

        $self->do_something( @_ );
    }
success_action (a code ref)

Called with:

    your self object
    the data you passed to add, edit or delete
    the action (add, edit or delete)
    the user request

Just like the cancel_action, but triggered when the user presses the Cancel button.

text_descr

Same as in CRUD.

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

use_clean_dates (optional, defaults to false)

Same as in CRUD.

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)

Same as in CRUD.

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.

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

Top

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

Top

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

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

 Gantry and the other Gantry::Plugins

AUTHOR

Top

Kevin Esteb

COPYRIGHT and LICENSE

Top

Copyright (c) 2006, Kevin Esteb

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.

Gantry documentation Contained in the Gantry distribution. 
package Gantry::Plugins::AjaxCRUD;

use strict;
use Carp;
use Data::FormValidator;

use Gantry::Utils::CRUDHelp qw( clean_dates clean_params form_profile );

use base 'Exporter';

our @EXPORT_OK = qw( select_multiple_closure );

#-----------------------------------------------------------
# Constructor
#-----------------------------------------------------------

sub new {
    my $class     = shift;
    my $callbacks = { @_ };

    unless ( defined $callbacks->{template} ) {
        $callbacks->{template} = 'form.tt';
    }

    return bless $callbacks, $class;
}

#-----------------------------------------------------------
# Accessors, so we don't misspell hash keys
#-----------------------------------------------------------

sub add_action {
    my $self = shift;

    if ( defined $self->{add_action} ) {
        return $self->{add_action};
    }
    else {
        croak 'add_action not defined or misspelled';
    }
}

sub edit_action {
    my $self = shift;

    if ( defined $self->{edit_action} ) {
        return $self->{edit_action}
    }
    else {
        croak 'edit_action not defined or misspelled';
    }
}

sub delete_action {
    my $self = shift;

    if ( defined $self->{delete_action} ) {
        return $self->{delete_action}
    }
    else {
        croak 'delete_action not defined or misspelled';
    }
}

sub setup_action {
    my $self = shift;

    if ( defined $self->{setup_action} ) {
        return $self->{setup_action}
    }
    else {
        croak 'setup_action not defined or misspelled';
    }
}

sub cancel_action {
    my $self = shift;

    if ( defined $self->{cancel_action} ) {
        return $self->{cancel_action}
    }
    else {
        croak 'cancel_action not defined or misspelled';
    }
}

sub success_action {
    my $self = shift;

    if ( defined $self->{success_action} ) {
        return $self->{success_action}
    }
    else {
        croak 'success_action not defined or misspelled';
    }
}

sub form {
    my $self = shift;

    if ( defined $self->{form} ) {
        return $self->{form}
    }
    else {
        croak 'form not defined or misspelled';
    }
}

sub text_descr {
    my $self = shift;
    return $self->{text_descr}
}

sub use_clean_dates {
    my $self = shift;
    return $self->{use_clean_dates};
}

sub turn_off_clean_params {
    my $self = shift;
    return $self->{turn_off_clean_params};
}

#-----------------------------------------------------------
# Methods users call
#-----------------------------------------------------------

#-------------------------------------------------
# $self->add( $your_self, { put => 'your', data => 'here' } )
#-------------------------------------------------
sub add {
    my ( $self, $your_self, $data ) = @_;

    eval {
        $self->setup_action->( $your_self, $data, 'add', $self->text_descr );
    };  # failure means they don't wan this

    my $params   = $your_self->get_param_hash();

    # Redirect if user pressed 'Cancel'
    if ( $params->{cancel} ) {

        return $self->cancel_action->( $your_self, $data, 'add', 'cancel' );

    }

    # get and hold the form description
    my $form = $self->form->( $your_self, $data );

    # Check form data
    my $show_form = 0;

    $show_form = 1 if ( keys %{ $params } == 0 );

    my $results = Data::FormValidator->check(
        $params,
        form_profile( $form->{fields} ),
    );

    $show_form = 1 if ( $results->has_invalid );
    $show_form = 1 if ( $results->has_missing );

    if ( $show_form ) {
        # order is important, first put in the form...
        $your_self->stash->view->form( $form );

        # ... then add error results
        if ( $your_self->method eq 'POST' ) {
            $your_self->stash->view->form->results( $results );
        }
    }
    else {
        # remove submit button entry
        delete $params->{submit};

        if ( $self->turn_off_clean_params ) {
            if ( $self->use_clean_dates ) {
                clean_dates( $params, $form->{ fields } );
            }
        }
        else {
            clean_params( $params, $form->{ fields } );
        }

        $self->add_action->( $your_self, $params, $data );

        # move along, we're all done here

        return $self->success_action->( $your_self, $data, 'submit', 'add' );
    }
} # END: add

#-------------------------------------------------
# $self->edit( $your_self, { put => 'your', data => 'here' } );
#-------------------------------------------------
sub edit {
    my ( $self, $your_self, $data ) = @_;

    eval {
        $self->setup_action->( $your_self, $data, 'edit', $self->text_descr );
    }; # failure means they don't wan this

    my %params = $your_self->get_param_hash();

    # Redirect if 'Cancel'
    if ( $params{cancel} ) {

        return $self->cancel_action->( $your_self, $data, 'cancel', 'edit' );

    }

    # get and hold the form description
    my $form = $self->form->( $your_self, $data );

    croak 'Your form callback gave me nothing' unless defined $form and $form;

    my $show_form = 0;

    $show_form = 1 if ( keys %params == 0 );

    # Check form data
    my $results = Data::FormValidator->check(
        \%params,
        form_profile( $form->{fields} ),
    );

    $show_form = 1 if ( $results->has_invalid );
    $show_form = 1 if ( $results->has_missing );

    # Form has errors
    if ( $show_form ) {
        # order matters, get form data first...
        $your_self->stash->view->form( $form );

        # ... then overlay with results
        if ( $your_self->method eq 'POST' ) {
            $your_self->stash->view->form->results( $results );
        }
    
    }
    # Form looks good, make update
    else {
        
        # remove submit button param
        delete $params{submit};

        if ( $self->turn_off_clean_params ) {
            if ( $self->use_clean_dates ) {
                clean_dates( \%params, $form->{ fields } );
            }
        }
        else {
            clean_params( \%params, $form->{ fields } );
        }

        $self->edit_action->( $your_self, \%params, $data );
        
        # all done, move along

        return $self->success_action->( $your_self, $data, 'submit', 'edit' );
    }
} # END: edit

#-------------------------------------------------
# $self->delete( $your_self, $confirm, { other => 'data' } )
#-------------------------------------------------
sub delete {
    my ( $self, $your_self, $yes, $data ) = @_;

    eval {
        $self->setup_action->(
                $your_self, $data, 'delete', $self->text_descr
        );
    }; # failure means they don't wan this

    if ( $your_self->params->{cancel} ) {

        return $self->cancel_action->( $your_self, $data, 'cancel', 'delete' );

    }

    if ( ( defined $yes ) and ( $yes eq 'yes' ) ) {

        $self->delete_action->( $your_self, $data );

        # Move along, it's already dead

        return $self->success_action->( $your_self, $data, 'submit', 'delete' );
    }
    else {
        $your_self->stash->view->form->message (
            'Delete ' . $self->text_descr() . '?'
        );
    }
}

#-----------------------------------------------------------
# Helper functions offered for export
#-----------------------------------------------------------

sub select_multiple_closure {
    my $field_name  = shift;
    my $db_selected = shift;

    return sub {
        my $id     = shift;
        my $params = shift;

        my @real_keys = grep ! /^\./, keys %{ $params };

        if ( @real_keys ) {
            return unless $params->{ $field_name };
            my @param_ids = split /\0/, $params->{ $field_name };
            foreach my $param_id ( @param_ids ) {
                return 1 if ( $param_id == $id );
            }
        }
        else {
            return $db_selected->{ $id };
        }
    };
}

1;

__END__