view release on metacpan or  search on metacpan

lib/Catalyst/Enzyme.pm  view on Meta::CPAN

    script\bookshelf_create.pl view TT Enzyme::TT

    #Create database
    ... left as an exercise for the reader (actually, see the tutorial) ...

    #Create Models for all tables
    script\bookshelf_create.pl model BookShelfDB Enzyme::CDBI dbi:SQLite:dbname=db/bookshelf.db

    #Create Controller
    script\bookshelf_create.pl controller Book Enzyme::CRUD BookShelfDB::Book


Browse to http://localhost:3000/book and see what it looks like
without any configuration.

See the L</DEMO APPLICATION> below for a ready-to-run example of the BookDB.

See the L</TUTORIAL> below for a detailed example of how to create an
application from the BookDB schema.



=head1 DESCRIPTION

Catalyst::Enzyme is a layer on top of the Catalyst framework providing
CRUD functionality for L<Class::DBI> models.

Enzyme uses convention and configuration to provide e.g. extensible
CRUD out-of-the-box, and a common way of dealing with error handling
etc.

It's not completely unlike L<Maypole> in this regard. However, at this
point Enzyme isn't as feature-rich as Maypole.

Enzyme is one way of bringing many Catalyst modules and concepts
together into a unified whole. There are other ways to do this
(obviously. This is, like... uh, Perl).


=head2 Documentation

First, look at these docs, and do the L</TUTORIAL>.

Then look at L</Further Documentation>.



=head1 WORKING WITH ENZYME


=head2 Introduction

Enzyme came about when I created Scaffolding CRUD code for some
tables. There was much duplication, both in Controllers and in
templates.

So I refactored.

The templates duplication resulted in
L<Catalyst::View::TT::ControllerLocal>, which allows you to override
templates or template fragments by placing them in a directory
specific to the Controller.

The Controller code duplication resulted in the class
L<Catalyst::Enzyme::CRUD::Controller>. This has since grown
significantly and now includes more robust CRUD behaviour, uniform
presentation of status and messages to the user.


=head2 Assumptions

Your application uses L<Class::DBI> based model classes.

You want CRUD functionality, either as part of your application
(perhaps as a mangagement interface for internal use), or just to get
started with something.

You are willing to read and understand the source (both code and
templates) in order to modify them. While Enzyme can get you started
faster and with less code, you need to make this your own
framework. Change it, adapt it to your needs.


=head2 Overview

At the bottom is a database table.

On top of the table there is a Catalyst L<Class::DBI> Model class
(which also inherits from L<Catalyst::Enzyme::CRUD::Model>). The Model
class provides some meta data so Enzyme can display the Model objects
properly.

For each Model class there is a CRUD Controller class (based on
L<Catalyst::Enzyme::CRUD::Controller> providing actions for L<create>,
L<edit>, etc.

There is a set of default TT templates to display the Model
objects. You can override templates per Controller.

There are helpers provided for creating these components. In most
cases you'll have to provide some meta data for the table.


=head2 Providing Meta Data

Refactoring meant moving details out of templates and into general
components. Sometimes this involved moving meta data out of the
application.

This information must be provided somehow, and the best we can do (if
it can't be figured out automatically) is to put it in one place. This
is done in the Model class' config->{crud} hash ref.

(Granted, some configurations are View related and really should be in
the View (i.e.the template?), but I don't see a way to do that right
now.)

See L<Catalyst::Enzyme::CRUD::Model> for details on what parameters
you should set for each Model class.

lib/Catalyst/Enzyme.pm  view on Meta::CPAN

    ... created files ...
    cd BookShelf

Run tests

    prove -Ilib t

Start server

    script\bookshelf_server.pl

Browsing to http://localhost:3000/ gets us the welcome screen.



=head2 Edit lib/BookShelf.pm

Add DefaultEnd and FormValidator

    use Catalyst qw/-Debug Static::Simple DefaultEnd FormValidator/;

Remove the welcome message from the default action

    # Hello World
    $c->response->body( $c->welcome_message );

and replace it with

    $c->res->redirect("/book");

This url doesn't exist yet, but we'll create it soon (so don't restart
the server just yet).

Note that the test C<t/01app.t> will fail from now on. Figure out
what:

    prove -Ilib -v t\01app.t

Ok, a redirect isn't C<is_success>. Since that test doesn't reflect
what the application does anymore, you should probably change
C<t/01app.t> to this:

    use Test::More tests => 1;
    use_ok( Catalyst::Test, 'BookShelf' );
    ok(request("/")->is_redirect, "Redirect ok");

And the test pass again. That's nice.

    prove -Ilib t


=head2 Create TT View

    script\bookshelf_create.pl view TT Enzyme::TT
    ... created files ...

This creates a special Enzyme TT View, standard templates in
./root/base/, as well as a css (named after your application) file in
./root/static/css/ .

The Enzyme TT View allows for overloading template fragments based on
the Controller (e.g. BookShelf::Controller::Book). It also provides a few
utility methods for the templates.

You'll probably want to modify the templates and the style sheet later
on to alter the global look of the application.

You'll probably want to copy some standard templates from
C<./root/base/> to e.g. <./root/book/) and modify them in order to
alter the web pages for only that part of the application.



=head2 Create the database

The bookdb.sql file is available in the C<t/tutorial/database>
directory. It's probably a good idea to take a look at it to get an
idea of what it provides.

    mkdir db
    dbish dbi:SQLite:dbname=db/bookshelf.db < ..\database\bookdb.sql


=head2 Create the CDBI Model

    script\bookshelf_create.pl model BookShelfDB Enzyme::CDBI dbi:SQLite:dbname=db/bookshelf.db
    ... created files ...

This creates the main CDBI class BookShelfDB. At this point it may be
practical to anchor the database file to the Catalyst home dir:

    dsn => 'dbi:SQLite:dbname=' . file(BookShelf->config->{home}, 'db/bookshelf.db'),


The helper also creates table classes for each table in the database.

While they work as it is, Enzyme could use some extra meta data about
the Model classes.



=head2 Configure the Book Model class

lib\BookShelf\Model\BookShelfDB\Book.pm

Add Add Class::DBI configuration:

    __PACKAGE__->columns(Stringify => "title");


The helper created the C<view_columns> and C<list_columns> from the
fields in the table. You're supposed to remove or change the order of
the columns to fit your application (if you like it the way it is,
just delete the lines altogether).

    #__PACKAGE__->columns(view_columns => qw/ author borrowed borrower format genre isbn pages publisher title year /);
    #__PACKAGE__->columns(list_columns => qw/ author borrowed borrower format genre isbn pages publisher title year /);

A third column group you can define here is C<edit_columns> (if not,
the C<view_columns> is used for the add/edit as well).