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.

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

This plugin provides no user-based access authentication or authorization. Please take care when deploying, and consider who will have access. It is possible to restrict the add/update/delete operations on data. See "TIPS AND TRICKS" for other suggestions.

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.

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:

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:

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

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

It is essential that you load the Catalyst::Plugin::Unicode::Encoding plugin to ensure proper decoding/encoding of incoming request parameters and the outgoing body response respectively. This is done in your MyApp.pm:

use Catalyst qw/ -Debug ConfigLoader Unicode::Encoding AutoCRUD /;

Additionally, when connecting to the database, add a flag to the connection parameters, specific to your database engine, that enables Unicode. See the following link for more details:

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:

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.

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.

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.

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:

<Plugin::AutoCRUD>
basepath admin
</Plugin::AutoCRUD>

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:

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

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:

The whole site is built from Perl Template Toolkit templates, and it is possible to override these shipped templates with your own files. This goes for both general files (CSS, top-level TT wrapper) as well as the site files mentioned in the next section.

To add these override paths, include the following directive in your configuration file:

It's possible to have multiple views of the source data, tailored in various ways. For example you might choose to hide some tables, or columns within tables, rename headings of columns, or disable updates or deletes.

This is all achieved through the sites configuration. Altering the default site simply allows for control of column naming, hiding, etc. Creating a new site allows you to present alternate configurations of the same source data.

When using this plugin out of the box you're already running within the default site, which unsurprisingly is called default. To override settings in this, create the following configuration stub, and fill it in with any of the options listed below:

In general, when you apply a setting to something at a higher level (say, a database), it percolates down to the child sections (i.e. the tables). For example, setting delete_allowed no on a database will prevent records from any table within that from being deleted.

Some of the options are global for a site, others apply to the database or table within it. To specify an option for one or the other, use the database and table names as they appear in the URL path:

This can be applied to either a database or a table; if applied to a database it percolates to all the tables, unless the table has a different setting.

The default is to allow updates to be made to existing records. Set this to a value of no to prevent this operation from being permitted. Widgets will also be removed from the user interface so as not to confuse users.

This can be applied to either a database or a table; if applied to a database it percolates to all the tables, unless the table has a different setting.

The default is to allow new records to be created. Set this to a value of no to prevent this operation from being allowed. Widgets will also be removed from the user interface so as not to confuse users.

This can be applied to either a database or a table; if applied to a database it percolates to all the tables, unless the table has a different setting.

The default is to allow deletions of records in the tables. Set this to a value of no to prevent deletions from being allowed. Widgets will also be removed from the user interface so as not to confuse users.

This option achieves two purposes. First, you can re-order the set of columns as they are displayed to the user. Second, by omitting columns from this list you can hide them from the main table views.

Provide a list of the column names (as the data source knows them) to this setting. This option must appear at the table level of your site config hierarchy. In Config::General format, this would look something like:

Any columns existing in the table, but not mentioned there, will not be displayed in the main table. They'll still appear in the record edit form, as some fields are required by the database schema so cannot be hidden. Columns will be displayed in the same order that you list them in the configuration.

You can alter the title given to any column in the user interface, by providing a hash mapping of column names (as the data source knows them) to titles you wish displayed to the user. This option must appear at the table level of your site config hierarchy. In Config::General format, this would look something like:

With this option you can swap out the set of templates used to generate the web front-end, and completely change its look and feel.

Currently you have two choices: either extjs2 which is the default and provides the standard full-featured ExtJS2 frontend, or skinny which is a read-only non-JavaScript alternative supporting listing, paging and sorting only.

Set the frontend in your site config at its top level. Note that you cannot set the frontend on a per-database or per-table basis, only per-site:

Be aware that setting the frontend to skinny does not restrict create or update access to your database via the AJAX API. For that, you still should set the *_allowed options listed above, as required.

So let's say you've created a dumbed down site for your users which is read-only (i.e. update_allowed no and delete_allowed no), and called the site simplesite in your configuration. You need to give the following URL to users:

.../autocrud/site/simplesite

You could also then place an access control on this path part in your web server (e.g. Apache) which is different from the default site itself.

To use your own database rather than the SQLite demo, edit examples/demo/demo.conf so that it contains the correct dsn, username, and password for your database. Upon restarting the application you should see your own data source instead.

An alternate application exists which demonstrates use of the display_name method on a DBIx::Class Row, to give row entries "friendly names". Follow all the instructions above but instead run the following server script:

Finally, the kitchen sink of other features supported by this module are demonstrated in a separate application. This contains many tables, each of which highlights one or more aspects of a relational database backend being rendered in AutoCRUD.

Follow all the instructions above, but instead run the following server script:

CatalystX::CRUD and CatalystX::CRUD:YUI are two distributions which allow you to create something similar but with full customization, and the ability to add more features. So, you trade effort for flexibility and power.

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.