Documentation

WORKING WITH ENZYME

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

Assumptions

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.

Overview

At the bottom is a database table.

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

Messages

Form validation

Form validation errors

Errors in the Controller

$c->stash->{message}, $c->stash->{error}

css: .error_text

Template: header.tt

Forward vs redirect

Enzyme will redirect (as opposed to forward) after any data modifying action (the do_* actions).

The reason for this is that there shouldn't be any destructive url lingering in the Location field in the browser (what happens if the user reloads the /book/do_delete/34 URL? It fails if course. Bad).

Forwarding between Controllers

Each Controller has a Model class associated with it (available in the $c->stash->{crud}->{model_class}), along with the rest of the meta data you set up in the Model class.

The stash contents is set automatically in the auto action when the request comes in. This is the current Controller (and it's Model).

So long as you forward to CRUD actions in the same Controller, this is fine.

But if you for some reason would like to forward to a CRUD action in another controller, you need to tell Enzyme to switch to a new current Controller. If the original request was for /genre/add_book and you would like to forward to /book/add, you would have to do this:

$c->forward("/book/set_crud_controller");
$c->forward("/book/add");

The templates use the c.uri_for_controller('action') helper method (from Catalyst::Enzyme::CRUD::View) to force the URIs to the current Controller.

Internationalization

Not supported at the moment. There are a few texts coming from the Controllers, but almost all text is in the templates.

Further Documentation

Look through the templates in ./root/base and make sure you have a basic understanding of what they do.

Read the source of Catalyst::Enzyme::CRUD::Controller to understand how you can use, adapt, and extend it. Or ignore it. You may have much better ways of doing things, or totally different needs for your application.

UPGRADING ENZYME

Tables

When you have created a new table, run the Model helper again, and it will create a Model class for the new table.

It will also generate Model classes for the existing tables, but with a .new extension. Just delete them.

Templates

When you want to install a new version of Catalyst::Enzyme, the thing most likely to break is the templates. That's natural, that's the part you most likely will have changed.

When that happens, re-generate the View, and merge any newly generated files with a .new suffix. If your files are in version control, the simplest thing may be to delete the templates, re-generate them and let the VCS help you merge them.

This is of course a slight annoyance, but I'll try to bundle template changes into one release instead of many small ones. Template changes are bound to happen less frequently over time as the feature-set of Catalyst::Enzyme becomes more stable.

Any template change will be noted in the Changes file.

DEMO APPLICATION

There is a demo application at t/tutorial/BookShelf which you should be able to run with

script\bookshelf_server -d

If the database doesn't work properly, you may need to re-create the SQLite database file db/bookshelf.db. See the "TUTORIAL" for instructions on how to do that.

The demo is a CRUD setup (basically the tutorial), with some minor enhancments to borrow/return books, to give an example of how to grow an application.

TUTORIAL

Let's take the Catalyst example BookDB application and see what it looks like with only a CRUD layer on top of the database.

Note: this was done using Windows, so make sure you adapt the / vs \ to your filesystem conventions.

Browse to http://localhost:3000/ at regular intervals during the setup to see the current state of the application.

If you're gonna do this yourself, the simplest thing is probably to do it from the t/tutorial directory. That way the database create script will be in place.

Rename the existing BookShelf application directory to something else, open up a shell in tutorial and go ahead...

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

Configure the Book Model class

lib\BookShelf\Model\BookShelfDB\Book.pm

Add Add Class::DBI configuration:

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

The helper created the view_columns and 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).

The column_monikers is optional, and except for the ISBN, this was also unnecessary. But since we had to override it, we had to start with the deafult column monikers.

rows_per_page => 10,

The rows_per_page controls paging when listing the Books. The deafult is 20 rows, but Books take a little more vertical space, so we'll go with 10. Actually, if you'd like to see the paging feature right away, set it to 3. Or you could just add a few books...

Create Book CRUD Controller

The most important thing to note in the created BookShelf\Controller\Book.pm is the sub where the Model file is specified:

sub model_class {
return("BookShelf::Model::BookShelfDB::Book");
}

Test the book CRUD

Now we finally have all the required components in place to take a look at the Book table. But why not run the tests again.

prove -Ilib t

All test should pass (and they don't really do much anyway, but at least the Controller tests make a request to the default action).

Run the server:

script\bookshelf_server.pl

When you surf around at http://localhost:3000/book and check out all the books you may notice that Borrower is a number, and so is Genre. That's because we haven't configured the other Models with a Stringify column yet.

When you add new Books, note how the title is mandatory. See what happens if you omit it.

Also note how the ISBN number is optional, but if there is anything entered, it must abide by the constraint. (I have no idea whether that's actually a proper constraint for ISBN numbers).

If you set the rows_per_page to 3, you should see the paging in action. If not, add a few books.

Add links between the tables

Edit the root/base/header.tt and add this inside the content div so we can jump between the tables:

The normal way to import the default FormValidator::Constraints would be

use Data::FormValidator::Constraints qw(:regexp_common :closures);

and the :closures group imports subs like email and phone into this namespace. But... since this is our model class, there is already field accessors by that names in our symbol table, and that will clash. Hence the use of Data::FormValidator::Constraints::email in the config.

__PACKAGE__->columns(Stringify=> qw/name/);

Thanks to the Stringify, the Borrower now displays as the name, not the PK in the Book listing.