NAME

Mojolicious::Plugin::Tables -- Quickstart and grow a Tables-Maintenance application

SYNOPSIS

    # in a new Mojolicious app..
 
    $app->plugin( Tables => {connect_info=>['dbi:Pg:dbname="mydatabase"', 'uid', 'pwd']} );

    # when ready to grow..

    $app->plugin( Tables => {model_class => 'StuffDB'} );

DESCRIPTION

Mojolicious::Plugin::Tables is a Mojolicious plugin which helps you grow a high-featured web app by starting with basic table / relationship maintenance and growing by overriding default behaviours.

By supplying 'connect_info' (DBI-standard connect parameters) you get a presentable database maintenance web app, featuring full server-side support for paged lists of large tables using 'Datatables' (datatables.net), plus ajax handling for browsing 1-many relationships, plus JQueryUI-styled select lists for editing many-to-1 picklists.

By supplying your own Model Class you can override most of the default behaviours and build an enterprise-ready rdbms-based web app.

By supplying your own templates for context-specific calls you can start to give your app a truly specialised look and feel.

STATUS

This is an early release. Guides and more override-hooks coming Real Soon Now.

GROWTH PATH

Ground Zero Startup

    tables dbi-connect-params..

The 'tables' script is supplied with this distribution. Give it standard DBI-compatible parameters on the commandline and it will run a minimal web-server at localhost:3000 to allow maintenance on the named database.

Day One

In your Mojolicious 'startup'..

    $self->plugin(Tables => { connect_info => [ connect-param, connect-param, .. ] };

Add this line to a new Mojolicious app then run it using any Mojo-based server (morbo, prefork, hypnotoad..) to achieve exactly the same functionality as the 'tables' script.

Day Two

    # templates/:table/{view,edit,dml,page}.html.ep
    # e.g. 
    # templates/artist/view.html.ep
    <h1>Artist: <%= $row %></h1>

For any :table in your database, create override-templates as required. e.g. The above code will give a very different look-and-feel when viewing a single Artist, but all other pages are unchanged. For better examples and to see which stash-variables are available, start by copying the distribution templates from ../Plugin/Tables/resources/templates into your own template area.

Infinity and Beyond

    $self->plugin(Tables => { model_class => 'MyDB' } );

Prepare your own model_class to override the default database settings which "Tables" has determined from the database. This class (and its per-table descendants) can be within or without your Mojolicious application. model_class implements the specification given in Mojolicious::Plugin::Tables::Model. This lets you start to customise and grow your web app.

CONFIGURATION

    $app->plugin(Tables => $conf) 

Where the full list of configuration options is:

layout

Provide an alternative 'wrapper' layout; typically the one from your own application. If you prepare one of these you will need to include most of the layout arrangements in the Day-One layout, i.e. the one at resources/templates/layouts/tables.html.ep. The easiest approach is to start by copying the packaged version into your own application and then change its look and feel to suit your requirements.

nohome

Unless you supply a true value for this, an automatic redirection will be in place from the root of your app to the '/tables' path. The redirection is there to make day-one functionality easy to find, but once your app grows you will not want this redirection.

model_class

See 'Customising Model Class'

connect_info

See 'Day One'

default_theme

To experiment with completely different colour themes, choose any standard JQueryUI theme name or "roll" your own as described here http://jqueryui.com/themeroller/. Our default is 'Redmond'.

DEBUGGING

To generate detailed trace info into the server log, export TABLES_DEBUG=1.

CAVEAT

We use dynamically-generated DBIx::Class classes. This technique does not scale well for very large numbers of tables. Previous (private) incarnations of this Framework used specially prepared high-performance versions of Class::DBI::Loader to speed this up. So that speeding-up at start-time is a TODO for this DBIx::Class-based release.

SOURCE and ISSUES REPOSITORY

Open-Sourced at Github: https://github.com/frank-carnovale/Mojolicious-Plugin-Tables. Please use the Issues register there.

COPYRIGHT AND LICENSE

Copyright (C) 2016, Frank Carnovale <frankc@cpan.org>

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.

SEE ALSO

Mojolicious, DBIx::Class::Schema::Loader, Mojolicious::Plugin::Tables::Model

cpanm Mojolicious::Plugin::Tables

perl -MCPAN -e shell
install Mojolicious::Plugin::Tables