NAME
CatalystX::ListFramework::Builder - Instant AJAX web front-end for
DBIx::Class, using Catalyst
VERSION
This document refers to version 0.24 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
schema_class My::Database::Schema
connect_info dbi:Pg:dbname=mydbname;host=mydbhost.example.com;
connect_info username
connect_info password
AutoCommit 1
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
When the web interface wants to display a column which references
another table, you can make things look much better by adding a custom
render method to your "DBIx::Class" Result Sources (i.e. the class files
for each table).
First, the application will look for a method called "display_name" and
use that. Here is an example which could be added to your Result Source
classes below the line which reads *DO NOT MODIFY THIS OR ANYTHING
ABOVE*, and in this case returns the data from the "title" column:
sub display_name {
my $self = shift;
return $self->title || '';
}
Failing the existence of a "display_name" method, the application
attempts to stringify the row object. Using stringification is not
recommended, although some people like it. Here is an example of a
stringification handler:
use overload '""' => sub {
my $self = shift;
return $self->title || '';
}, fallback => 1;
If all else fails the application prints the best hint it can to
describe the foreign row. This is something approximating the name of
the foreign table, the names of the primary keys, and associated values.
It's better than stringifying the object the way Perl does, anyway.
One other very important tip: 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. The
interface will look much better as a result.
Finally, buried within one of the modules in this application are some
filters, which are applied to data of certain types as it enters or
leaves the database. If you find a particular data type is not being
rendered correctly, please drop the author a line at the email address
below, explaining what you'd like to see instead.
Download and install ExtJS
You'll need to download the ExtJS Javascript Library (version 2.1 or
later) from this web page:
.
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
schema_class My::Database::Schema
connect_info dbi:Pg:dbname=mydbname;host=mydbhost.example.com;
connect_info username
connect_info password
AutoCommit 1
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:
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
.
* 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 ""
COPYRIGHT & LICENSE
Bundled images are Copyright (c) 2006 Mark James, and are from
.
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