The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
RapidApp-1.3404
River stage one • 5 direct dependents • 5 total dependents
29 ++
/ Catalyst::Plugin::RapidApp::RapidDbic

NAME

Catalyst::Plugin::RapidApp::RapidDbic - Instant web front-ends for DBIx::Class

QUICK START

To get started very quickly with a new app, see the RapidDbic helper for bootstrapping a new app in the manual:

SYNOPSIS

 package MyApp;
 
 use Catalyst   qw/ RapidApp::RapidDbic /;

Then, also in the main Catalyst app class:

 __PACKAGE__->config(
 
    'Plugin::RapidApp::RapidDbic' => {
      dbic_models => ['DB','OtherModel'],
      
      # All custom configs optional...
      configs => {
        DB => {
          grid_params => {
            # ...
          },
          TableSpecs => {
            # ...
          }
        },
        OtherModel => {
          # ...
        }
      }
    }
 );

Or, within individual DBIC::Schema model class(es):

 package MyApp::Model::DB;
 use Moo;
 extends 'Catalyst::Model::DBIC::Schema';

 __PACKAGE__->config(
    schema_class => 'MyApp::DB',
 
    connect_info => {
       # ...
    },
 
    RapidDbic => {
 
      # All custom configs optional...
      grid_params => {
        # to make all grids editable:
        '*defaults' => {
          updatable_colspec   => ['*'],
          creatable_colspec   => ['*'],
          destroyable_relspec => ['*'],
          # ...
        },
        MySourceA => {
          persist_immediately => {
             # Save only when clicking "Save" button...
             create  => 0, update  => 0, destroy => 0
          },
          # ...
        }
      },
      TableSpecs => {
        MySourceA => {
          title          => 'My Source Abba!',
          title_multi    => 'Abbas',
          iconCls        => 'icon-apple',
          multiIconCls   => 'icon-apples',
          # ...
        },
        SourceB => {
          display_column => 'foo',
          columns => {
            foo => { 
              title => 'Foo',
              # ...
            }
          }
        }
      },
      table_class => 'MyApp::Module::CustGridModule',
      virtual_columns => {
        # ...
      }
    }

DESCRIPTION

The RapidDbic plugin provides a very high-level, abstract configuration layer for initializing a structure of interfaces for accessing DBIC::Schema models for Catalyst/RapidApp. These interfaces are fully functional out-of-the-box, but also provide a robust base which can be configured and extended into various forms of custom applications.

RapidDbic itself simply assembles and configures other RapidApp plugins and modules into a useful, working combination without any fuss, while also providing configuration hooks into those sub-modules across different layers. This includes the TabGui plugin for the main interface and navigation structure, and sets of DBIC-aware modules such as grids, forms and trees.

This hooks into a very broad ecosystem of highly customizable and extendable modules which are still in the process of being fully documented... The unconfigured, default state resembles a database admin utility, with powerful CRUD features, query builder, batch modify forms, and so on.

RapidDbic is also designed to work with other, high-level plugins to access additional turn-key application-wide functionality, such as access and authorization with the AuthCore plugin and saved user-views with the NavCore plugin.

CONFIG

The only required config option is specifying at least one DBIC::Schema model to enable. This can be achieved either with the dbic_models option in the plugin config key 'Plugin::RapidApp::RapidDbic' within the main Catalyst app class/config, or by specifying a 'RapidDbic' config key in the model class(es) itself (see SYNOPSIS).

The optional additional config options for each model are then divided into two main sections, grid_params and TableSpecs, which are each further divided into each source name in the DBIC schema.

grid_params

The grid_params section allows overriding the parameters to be supplied to the RapidApp module which is automatically built for each source (with a menu point for each in the navtree). By default, this is the grid-based module Catalyst::Plugin::RapidApp::RapidDbic::TableBase, but can be changed (with the grid_class config option, see below) to any module extending a DBIC-aware RapidApp module (which are any of the modules based on the "DbicLink" ecosystem) which doesn't even necesarily need to be derived from a grid module at all...

For convenience, the special source name '*defaults' can be used to set params for all sources at once.

The DbicLink modules configuration documentation is still in-progress.

TableSpecs

TableSpecs are extra schema metadata which can optionally be associated with each source/columns. These provide extra "hints" for how to represent the schema entities in different application interface contexts. TableSpec data is passive and is consumed by all DBIC-aware RapidApp Modules for building their default configuration(s).

For a listing of the different TableSpec data-points which are available, see the TableSpec documentation in the manual:

grid_class

Specify a different RapidApp module class name to use for the source. The default is Catalyst::Plugin::RapidApp::RapidDbic::TableBase. The grid_params for each source are supplied to the constructor of this class to create the module instances (for each source).

grid_class can be supplied at the top of the RapidDbic config to apply to all models and all sources, within the RapidDbic config at the model level to apply to all sources within the given model, or in the individual source config within grid_params to apply to only the individual source.

virtual_columns

Automatically inject virtual columns via config into the sources... More documentation TDB.

In the meantime, see the virtual_column example in the Chinook Demo:

PLACK INTERFACE (QUICK START)

There is also now a Plack interface available which can be used to generate a fully working RapidDbic-based app with a working config on-the-fly that can then be mounted like any Plack app:

For instant gratification, a script-based wrapper is also available which can fire up an app with a single shell command and dsn argument:

SEE ALSO

AUTHOR

Henry Van Styn <vanstyn@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by IntelliTree Solutions llc.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.