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: