NAME

Dancer::Plugin::SimpleCRUD - very simple CRUD (create/read/update/delete)

DESCRIPTION

A plugin for Dancer web applications, to use a few lines of code to create appropriate routes to support creating/editing/deleting/viewing records within a database table. Uses CGI::FormBuilder to generate, process and validate forms, Dancer::Plugin::Database for database interaction and HTML::Table::FromDatabase to display lists of records.

SYNOPSIS

    # In your Dancer app,
    use Dancer::Plugin::SimpleCRUD;

    # Simple example:
    simple_crud(
        record_title => 'Widget',
        prefix => '/widgets',
        db_table => 'widgets',
    );

    # The above would create a route to handle C</widget/add> and
    # C</widget/:id>, presenting a form to add/edit a Widget respectively.
    # All fields in the database table would be editable.

    # A more in-depth synopsis, using all options:
    simple_crud(
        record_title => 'Widget',
        prefix => '/widgets',
        db_table => 'widgets',
        labels => {
            country => 'Country of Origin',
            type    => 'Widget Type', 
        },  
        validation => {
            weight => qr/\d+/,
        },
        input_types => {
            supersecret => 'password',
            lotsoftext' => 'textarea',
        },
        key_column => 'sku',
        editable_columns => [ qw( f_name l_name adr_1 ),
        display_columns => [ qw( f_name l_name adr_1 ),
        deleteable => 1,
        editable => 1,
        sortable => 1,
        paginate => 300,
        template => 'simple_crud.tt',
        query_auto_focus => 1,
        downloadable => 1,
    );

USAGE

This plugin provides a simple_crud keyword, which takes a hash of options as described below, and sets up the appropriate route to present add/edit/delete options.

OPTIONS

The options you can pass to simple_crud are:

record_title (required)

What we're editing, for instance, if you're editing widgets, use 'Widget'. Will be used in form titles (for instance "Add a ...", "Edit ..."), and button labels.

prefix (required)

The prefix for the routes which will be created. Given a prefix of /widgets, then you can go to /widgets/new to create a new Widget, and /widgets/42 to edit the widget with the ID (see keu_column) 42.

db_table (required)

The name of the database table.

key_column (optional, default: 'id')

Specify which column in the table is the primary key. If not given, defaults to id.

db_connection_name (optional)

We use Dancer::Plugin::Database to obtain database connections. This option allows you to specify the name of a connection defined in the config file to use. See the documentation for Dancer::Plugin::Database for how multiple database configurations work. If this is not supplied or is empty, the default database connection details in your config file will be used - this is often what you want, so unless your app is dealing with multiple DBs, you probably won't need to worry about this option.

labels (optional)

A hashref of field_name => 'Label', if you want to provide more user-friendly labels for some or all fields. As we're using CGI::FormBuilder, it will do a reasonable job of figuring these out for itself usually anyway - for instance, a field named first_name will be shown as First Name.

input_types (optional)

A hashref of field_name => input type, if you want to override the default type of input which would be selected by CGI::FormBuilder or by our DWIMmery (by default, password fields will be used for field names like 'password', 'passwd' etc, and text area inputs will be used for columns with type 'TEXT').

Valid values include anything allowed by HTML, e.g. text, select, textarea, radio, checkbox, password, hidden.

validation (optional)

A hashref of validation criteria which should be passed to CGI::FormBuilder.

acceptable_values (optional)

A hashref of arrayrefs to declare that certain fields can take only a set of acceptable values, for instance:

  { foo => [ qw(Foo Bar Baz) ] }

editable_columns (optional)

Specify an arrayref of fields which the user can edit. By default, this is all columns in the database table, with the exception of the key column.

<not_editable_columns> (optional)

Specify an arrayref of fields which should not be editable.

required (optional)

Specify an arrayref of fields which must be completed. If this is not provided, DWIMmery based on whether the field is set to allow null values in the database will be used - i.e. if that column can contain null, then it doesn't have to be completed, otherwise, it does.

deletable

Specify whether to support deleting records. If set to a true value, a route will be created for /prefix/delete/:id to delete the record with the ID given, and the edit form will have a "Delete $record_title" button.

editable

Specify whether to support editing records. Defaults to true. If set to a false value, it will not be possible to add or edit rows in the table.

sortable

Specify whether to support sorting the table. Defaults to false. If set to a true value, column headers will become clickable, allowing the user to sort the output by each column, and with ascending/descending order.

paginate

Specify whether to show results in pages (with next/previous buttons). Defaults to undef, meaning all records are shown on one page (not useful for large tables). When defined as a number, only this number of results will be shown.

display_columns

Specify an arrayref of columns that should show up in the list. Defaults to all.

template

Specify a template that will be applied to all output. This template must have a "simple_crud" placeholder defined or you won't get any output. This template must be located in your "views" directory. Any global layout will be applied automatically because this option causes the module to use the "template" keyword.

query_auto_focus

Specify whether to automatically set input focus to the query input field. Defaults to true. If set to a false value, focus will not be set. The focus is set using a simple inlined javascript.

downloadable

Specify whether to support downloading the results. Defaults to false. If set to a true value, The results show on the HTML page can be downloaded as CSV/TSV/JSON/XML. The download links will appear at the top of the page.

DWIMmery

This module tries to do what you'd expect it to do, so you can rock up your web app with as little code and effort as possible, whilst still giving you control to override its decisions wherever you need to.

Field types

CGI::FormBuilder is excellent at working out what kind of field to use by itself, but we give it a little help where needed. For instance, if a field looks like it's supposed to contain a password, we'll have it rendered as a password entry box, rather than a standard text box.

If the column in the database is an ENUM, we'll limit the choices available for this field to the choices defined by the ENUM list. (Unless you've provided a set of acceptable values for this field using the acceptable_values option to simple_crud, in which case what you say goes.)

AUTHOR

David Precious, <davidp@preshweb.co.uk>

ACKNOWLEDGEMENTS

Alberto Simões (ambs)

WK

Johnathan Barber

saberworks

BUGS

Please report any bugs or feature requests to bug-dancer-plugin-simplecrud at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Dancer-Plugin-SimpleCRUD. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

CONTRIBUTING

This module is developed on Github:

http://github.com/bigpresh/Dancer-Plugin-SimpleCRUD

Bug reports, ideas, suggestions, patches/pull requests all welcome.

Even just a quick "Hey, this is great, thanks" or "This is no good to me because..." is greatly appreciated. It's always good to know if people are using your code, and what they think.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Dancer::Plugin::SimpleCRUD

You may find help with this module on the main Dancer IRC channel or mailing list - see http://www.perldancer.org/

You can also look for information at:

• RT: CPAN's request tracker

  http://rt.cpan.org/NoAuth/Bugs.html?Dist=Dancer-Plugin-SimpleCRUD

• AnnoCPAN: Annotated CPAN documentation

  http://annocpan.org/dist/Dancer-Plugin-SimpleCRUD

• CPAN Ratings

  http://cpanratings.perl.org/d/Dancer-Plugin-SimpleCRUD

• Search CPAN

  http://search.cpan.org/dist/Dancer-Plugin-SimpleCRUD/

ACKNOWLEDGEMENTS

Alberto Simões (ambs)

Jonathan Barber

saberworks

jasonjayr

LICENSE AND COPYRIGHT

Copyright 2010-11 David Precious.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

cpanm Dancer::Plugin::SimpleCRUD::ParamsObject

perl -MCPAN -e shell
install Dancer::Plugin::SimpleCRUD::ParamsObject