NAME Catalyst::Plugin::AutoCRUD - Instant AJAX web front-end for DBIx::Class VERSION This document refers to version 0.57 of Catalyst::Plugin::AutoCRUD PURPOSE You have a database, and wish to have a basic web interface supporting Create, Retrieve, Update, Delete and Search, with little effort. This module is able to create such interfaces on the fly. They are a bit whizzy and all Web 2.0-ish. SYNOPSIS If you already have a Catalyst app with DBIx::Class models configured: use Catalyst qw(AutoCRUD); # <-- add the plugin name here in MyApp.pm Now load your app in a web browser, but add "/autocrud" to the URL path. Alternatively, to connect to an external database if you have the DBIX::Class schema available, use the "ConfigLoader" plugin with the following config: schema_class My::Database::Schema connect_info dbi:Pg:dbname=mydbname;host=mydbhost.example.com; connect_info username connect_info password AutoCommit 1 If you don't have the DBIx::Class schema available, just omit the "schema_class" option (and have DBIx::Class::Schema::Loader installed). 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). Almost all the information required by the plugin 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 Read Me First If you created your "DBIx::Class" Schema some time ago, perhaps using an older version of "DBIx::Class::Schema::Loader", then it might well be lacking some configuration which is required to get the best results from this plugin. Common omissions in column configurations include "is_foreign_key", "join_type", "is_nullable", and "is_auto_increment". Of course it's also good practice to have your "DBIx::Class" Schema closely reflect the database schema anyway. To automatically bring things up to date, download the latest version of DBIx::Class::Schema::Loader from CPAN (which may be 0.05 or a pre-release), and use the output from that. If you don't yet have a Schema, continue reading and Scenario 2, below, will cover the steps required. Scenario 1: Plugin to an existing Catalyst App This mode is for when you have written your Catalyst application, but the Views are catering for the users and as an admin you'd like a more direct, secondary web interface to the database. package AutoCRUDUser; use Catalyst qw(AutoCRUD); __PACKAGE__->setup; 1; Adding "Catalyst::Plugin::AutoCRUD" as a plugin to your Catalyst application, as above, causes it to scan your existing Models. If any of them are built using Catalyst::Model::DBIC::Schema, they are automatically loaded. This mode of operation works even if you have more than one database. You will be offered a Home screen to select the database, and then another menu to select the table within that. Remember that the pages available from this plugin will be located under the "/autocrud" path of your application. Use the "basepath" option if you want to override this. Scenario 2: Frontend for an existing "DBIx::Class::Schema" based class In this mode, "Catalyst::Plugin::AutoCRUD" is running standalone, in a sense as the Catalyst application itself. Your main application file looks almost the same as in Scenario 1, except you'll need the "ConfigLoader" plugin: package AutoCRUDUser; use Catalyst qw(ConfigLoader AutoCRUD); __PACKAGE__->setup; 1; For the configuration, you need to tell AutoCRUD which package contains the "DBIx::Class" schema, and also provide database connection parameters. schema_class My::Database::Schema connect_info dbi:Pg:dbname=mydbname;host=mydbhost.example.com; connect_info username connect_info password AutoCommit 1 The "Model::AutoCRUD::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". Remember that the pages available from this plugin will be located under the "/autocrud" path if your application. Use the "basepath" option if you want to override this. "DBIx::Class" setup You will of course need the "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 (in the configuration example above we used "My::Database::Schema"). 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", { debug => 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 (one of the paths shown at the end of "perl -V"). Scenario 3: Lazy loading a "DBIx::Class" schema If you're in such a hurry that you can't create the "DBIx::Class" schema, as shown in the previous section, then "Catalyst::Plugin::AutoCRUD" is able to do this on the fly, but it will slow the application's startup just a little. The application file and configuration are very similar to those in Scenario two, above, except that you omit the "schema_class" configuration option because you want AutoCRUD to generate that on the fly (rather than reading an existing one from disk). package AutoCRUDUser; use Catalyst qw(ConfigLoader AutoCRUD); __PACKAGE__->setup; 1; connect_info dbi:Pg:dbname=mydbname;host=mydbhost.example.com; connect_info username connect_info password AutoCommit 1 When AutoCRUD loads it will connect to the database and use the DBIx::Class::Schema::Loader module to reverse engineer its schema. To work properly you'll need the very latest version of that module (at least 0.05, or the most recent development release from CPAN). The other drawback to this scenario (other than the slower operation) is that you have no ability to customize how foreign, related records are shown. A related record will simply be represented as something approximating the name of the foreign table, the names of the primary keys, and associated values (e.g. id(5)). TIPS AND TRICKS Update your "DBIx::Class" Result Classes If you created your "DBIx::Class" Schema some time ago, perhaps using an older version of "DBIx::Class::Schema::Loader", then it might well be lacking some configuration which is required to get the best results from this plugin. Common omissions in column configurations include "is_foreign_key", "join_type", "is_nullable", and "is_auto_increment". Of course it's also good practice to have your "DBIx::Class" Schema closely reflect the database schema anyway. To automatically bring things up to date, download the latest version of DBIx::Class::Schema::Loader from CPAN (which may be 0.05 or a pre-release), and use the output from that. More detail is given in the "TROUBLESHOOTING" section, below. Representing related records 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 Classes (i.e. the class files for each table). First, the plugin will look for a method called "display_name" and use that. Here is an example which could be added to your Result Class files 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 plugin 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 plugin 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. Textfields and Textareas When the plugin creates a web form for adding or editing, it has to choose whether to show a Textfield or Textarea for text-type fields. If you have set a "size" option in add_columns() within the Schema, and this is less than or equal to 40, a Textfield is used. Otherwise, if the "size" option is larger than 40 or not set, then an auto-expanding, scrollable Textarea is used. Column names with spaces The plugin will handle most tricky names, but you should remember to pass some required extra quoting hints to DBIx::Class when it makes a connection to your database: # most databases: { quote_char => q{`}, name_sep => q{.} } # SQL Server: { quote_char => [qw/[ ]/], name_sep => q{.} } For more information see the DBIx::Class::Storage::DBI manual page or ask on the DBIx::Class mail list. Database IO filters 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. Relocating AutoCRUD to another URL path If you want to use this application as a plugin with another Catalyst system, it should work fine, but you probably want to serve pages under a different path on your web site. To that end, the plugin by default places its pages under a path part of ".../autocrud/". You can change this by adding the following option to your configuration file: basepath admin In the above example, the path ".../admin/" will contain the AutoCRUD application, and all generated links in AutoCRUD will also make use of that path. Remember this is added to the "base" of your Cataylst application which, depending on your web server configuration, might also have a leading path. To have the links based at the root of your application (which was the default behaviour of "CatalystX::ListFramework::Builder", set this variable to an empty string in your configuration: basepath "" Using your own ExtJS libraries The plugin will use copies of the ExtJS libraries hosted in the CacheFly content delivery network out there on the Internet. Under some circumstances you'll want to use your own hosted copy, for instance if you are serving HTTPS (because browsers will warn about mixed HTTP and HTTPS content). In which case, you'll need to download the ExtJS Javascript Library (version 2.2+ recommended), 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, like so: extjs2 /static/javascript/extjs-2 Use the "extjs2" option as shown above to specify the URL path to the libraries. This will be used in the templates in some way like this: