NAME
CatalystX::ListFramework::Builder - Instant AJAX web front-end for DBIx::Class, using Catalyst
VERSION
This document refers to version 0.19 of CatalystX::ListFramework::Builder
WARNING
This is an ALPHA RELEASE. I'd really appreciate any bug reports; you can use the CPAN RT bug tracking system, or email me (Oliver) directly at the address at the bottom of this page.
PURPOSE
You have a database schema available through DBIx::Class, and wish to have a basic web interface supporting Create, Retrieve, Update, Delete and Search, with little effort.
This module, with only a few lines of configuration, is able to create such interfaces on the fly. They are a bit whizzy and all Web 2.0-ish.
SYNOPSIS
A configuration file somewhere on your system:
# Config::General formal
# [listframeworkuser.conf] in Config::General format
base http://mywebserver.example.com
javascript /javascript/extjs-2
<Model::DBIC>
schema_class My::Database::Schema
connect_info dbi:Pg:dbname=mydbname;host=mydbhost.example.com;
connect_info username
connect_info password
<connect_info>
AutoCommit 1
</connect_info>
</Model::DBIC>And in the cgi-bin area of your web server:
package ListFrameworkUser;
use Catalyst qw(ConfigLoader +CatalystX::ListFramework::Builder);
__PACKAGE__->setup;
1;Now going to http://mywebserver.example.com/cgi-bin/tablename will render the web frontend for a table in your database. This can be much refined; see "USAGE", below.
DESCRIPTION
This module contains an application which will automatically construct a web interface for a database on the fly. The web interface supports Create, Retrieve, Update, Delete and Search operations.
The interface is not written to static files on your system, and uses AJAX to act upon the database without reloading your web page (much like other Web 2.0 appliactions, for example Google Mail).
The goals of the system are to require as little repetition of effort on your part as possible - the DRY principle (Don't Repeat Yourself). Almost all the information required is retrieved from the DBIx::Class ORM frontend to your database, which it is expected that you have already set up (although see "USAGE", below). This means that any change in database schema ought to be reflected immediately in the web interface after a page refresh.
USAGE
DBIx::Class setup
You will need DBIx::Class schema to be created and installed on your system. The recommended way to do this quickly is to use the excellent DBIx::Class::Schema::Loader module which connects to your database and writes DBIx::Class Perl modules for it.
Pick a suitable namespace for your schema, which is not related to this application. For example DBIC::Database::Foo::Schema for the Foo database. Then use the following command-line incantation:
perl -MDBIx::Class::Schema::Loader=make_schema_at,dump_to_dir:. -e \
'make_schema_at("DBIC::Database::Foo::Schema", { relationships => 1 }, \
["dbi:Pg:dbname=foodb;host=mydbhost.example.com","user","pass" ])'This will create a directory (such as DBIC) which you need to move into your Perl Include path.
DBIx::Class helpers
NB: THE STRINGIFICATION HERE IS DEPRECATED - MORE DETAILS IN THE NEXT RELEASE.
You really should add some stringification to these DBIx::Class schema otherwise the web interface will contain strange data. Add a stringify routine to the bottom of each schema file; something like this:
use overload '""' => sub {
my $self = shift;
return $self->title;
}, fallback => 1;In this example the row stringifies to the title column but you can of course return anything you wish.
Also, for those columns where your database uses an auto-incremented value, add the is_auto_increment => 1, option to the relevant hash in add_columns(). This will let the application know you don't need to supply a value for new or updated records.
Download and install ExtJS
You'll need to download the ExtJS Javascript Library (version 2.1 or later) from this web page: http://extjs.com/products/extjs/download.php.
Install it to your web server in a location that it is able to serve as static content. Make a note of the path used in a URL to retrieve this content, as it will be needed in the application configuration file, below.
Application configuration file
Create the application configuration file, an example of which is below:
base http://mywebserver.example.com
javascript /javascript/extjs-2
<Model::DBIC>
schema_class My::Database::Schema
connect_info dbi:Pg:dbname=mydbname;host=mydbhost.example.com;
connect_info username
connect_info password
<connect_info>
AutoCommit 1
</connect_info>
</Model::DBIC>The application needs to know where your copy of ExtJS (version 2.1 or later) is, on the web server. Use the javascript option as shown above to specify the URL path to the libraries. This will be used in the templates in some way like this:
<script type="text/javascript" src="[% c.base %][% c.javascript %]/ext-all.js" />The Model::DBIC section must look (and be named) exactly like that above, except you should of course change the schema_class value and the values within connect_info.
Catalyst application
The final step is to write a very small file which allows this module to bootstrap a Catalyst application around your database. Locate on your web server the area where Perl content is executed, and create a file as below:
package ListFrameworkUser;
use Catalyst qw(ConfigLoader +CatalystX::ListFramework::Builder);
__PACKAGE__->setup;
1;Let your web server know that this file is to be executed for any request which comes to its location.
If necessary, you'll need to let the ConfigLoader plugin know of the whereabouts of your application configuration file. See the Catalyst::Plugin::ConfigLoader documentation for more details, although here is a brief example of the change required:
__PACKAGE__->config( 'Plugin::ConfigLoader' => { file => 'myapp.conf' } );
__PACKAGE__->setup;Accessing the application from your browser
Presumably the location of the Catalyst application created in the previous section maps to a particular URL path. Follow this path with the name of a table in the database, and you should be presented with a table of data.
EXAMPLES
There is an examples directory included with this distribution which includes the files necessary to set up a small demo application with SQLite3.
LIMITATIONS
- Single column primary key
-
There's no support for multiple column primary keys (composite/compound keys). This has saved a lot of time in development because it greatly simplifies the Catalyst and DBIx::Class code. However if you're desperate for this feature, drop me a line because you might be able to buy some of my time to do the work required.
REQUIREMENTS
ExtJS Javascript Library version 2.1 or later, from http://extjs.com.
Catalyst::Runtime >= 5.70
Catalyst::Model::DBIC::Schema
Catalyst::View::JSON
Catalyst::View::TT
Class::C3
SEE ALSO
CatalystX::ListFramework is similar but has no dependency on Javascript (though it can use it for fancy auto-complete searches), and it also allows you to control which columns are rendered in the display.
ACKNOWLEDGEMENTS
Without the initial work on CatalystX::ListFramework by Andrew Payne and Peter Edwards this package would not exist. If you are looking for something like this module but without the dependency on Javascript, please do check out CatalystX::ListFramework.
AUTHOR
Oliver Gorwits <oliver.gorwits@oucs.ox.ac.uk>
Much of the design of this system came from CatalystX::ListFramework, by Andrew Payne and Peter Edwards.
COPYRIGHT & LICENSE
Bundled images are Copyright (c) 2006 Mark James, and are from http://www.famfamfam.com/lab/icons/silk/.
The rest is Copyright (c) Oliver Gorwits 2008. All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA