view release on metacpan or  search on metacpan

lib/CatalystX/ListFramework.pm  view on Meta::CPAN

package CatalystX::ListFramework;
use HTML::Widget;
use File::Slurp;
use Data::Dumper;
use Carp;

use strict;
use warnings;
our $VERSION = '0.5';
require 5.8.1;

=head1 NAME

CatalystX::ListFramework - foundations for displaying and editing lists (CRUD) in a Catalyst application

=head1 SYNOPSIS

    package MyApp::Controller::Foo;
    use base 'Catalyst::Controller';
    use CatalystX::ListFramework;
    
    sub listandsearch :Local {
        my ($self, $c, $kind) = @_;
        my $lf = CatalystX::ListFramework->new($kind, $c);
        my $restrict = {};
        $lf->stash_listing('myview', 'myprefix', $restrict);
        $c->stash->{template} = 'list-and-search.tt';
    }

    sub get :Local {
        my ($self, $c, $kind, $id) = @_;
        my $lf = CatalystX::ListFramework->new($kind, $c);
        $lf->stash_infoboxes({'me.id' => $id}); 
        $c->stash->{kind} = $kind;
        $c->stash->{id} = $id;  # the update form adds this to the URL
        $c->stash->{template} = 'detail.tt';
    }
    
    sub update :Local {
        my ($self, $c, $kind, $id) = @_;
        my $lf = CatalystX::ListFramework->new($kind, $c);
        $lf->update_from_query({'me.id' => $id}); 
        $c->res->redirect("/listandsearch/$kind");
    }
    
    sub create :Local {
        my ($self, $c, $kind) = @_;
        my $lf = CatalystX::ListFramework->new($kind, $c);
        my $id = $lf->create_new; 
        $c->res->redirect("/get/$kind/$id");
    }

=head1 DESCRIPTION

Displaying tabulated lists of database records, updating those records and
creating new ones is a common task in Catalyst applications.
This class supplies such lists, and forms to edit such records, to a set of
templates, using simple definition files and your L<DBIx::Class> Catalyst
model. A search form is also supplied, which can include JSON-powered
ExtJS comboboxes (see L<http://www.extjs.com/>).

To run the included demo application, grab a copy of ExtJS, then

    cd t/
    ln -s /path/to/extjs/ static/extjs-1.1
    lib/script/testapp_server.pl

then

    firefox http://localhost:3000/start
    
Please see L<BUGS> about some SQLite issues with the demo app.
The noninteractive test suite is

    perl live-test.pl
    

=head1 DEFINITION FILES

ListFramework is driven by a set of definition files, found under C<formdef/>, one pair per schema class (table).
These are divided into 'master' files and 'site' files and are named I<kind>.form.
Files under C<master/> describe a I<kind>'s source, what fields it has available, and how it is
associated with other schema classes.
Files under C<site/> describe how the data is displayed on the page.
This division, and the naming, implies that a vendor (you) could supply the master files, while a particular
installation could use customised site files to suit their needs.

These are best understood by looking at the example files.

=head2 Files under /master

The sections in these files are:

=over

=item title

A title, displayed on various screens.

=item model

The DBIx::Class model to use.

=item uses

This is a hashref linking this schema to others, in the form C<< field => 'kind' >>.
In site files, you can then use C<field.> (or several ones nested) to access the foreign schema, for example
"C<fromalbum.artist.name>". C<field> must be listed in the schema as a column and have a matching belongs_to relationship.

=item columns

This hashref species what columns the schema makes available and provides some metadata,
such as column headings, default values and types.

The 'field' property may be an arrayref, all elements of which are concatenated for display.
Static text can be specified using a scalar ref, and you can call functions from the Helper class by
specifying C<function(field)>. For example,

    field => [ \'(', uc(surname), \')' ]