/ 
CGI-FormBuilder-Config-Simple-0.07
River stage zero No dependents
/ CGI::FormBuilder::Config::Simple

NAME

CGI::FormBuilder::Config::Simple - deploy web forms w/ .ini file

VERSION

Version 0.07

SYNOPSIS

This module exists to synthesize the abstractions of CGI::FormBuilder with those of Config::Simple to make it nearly possible to deploy a working form and database application by simply configuring an ini file. Add to that config file your data processing routines, perhaps a template from the design team and you are done. This module handles converting a config file into a form, validating user input and all that.

A developer would still be required to write methods to process their data, but much of the rest of the work will be covered by this modules' methods, and those of the ones just cited.

For some sample code, please see: t/My/Module/Test.pm which provides scaffolding for the test suite.

-- signup.cgi --

use lib qw(lib);
use MyModule::Signup;
    # see below for details . . . 

my $debug_level = 0; # raise to 3 for noisy logs 
my $signup = MyModule::Signup->new({ config_file => '/path/to/config/file.ini' });
    # should create a config object respecting ->param() method 
    # and embed that object at $self->{'cfg'}
my $signup_form_html = $signup->render_web_form('sign_up',$debug_level) or
    carp("$0 died rendering a signup form. $signup->errstr. $!");

1;

-- /lib/MyModule/Signup.pm -- 

package MyModule::Signup;

use base 'CGI::FormBuilder::Config::Simple';

sub new {
  my $class = shift;
  my $defaults = shift;
  my $self = {};

  $self->{'cfg'} = Config::Simple::Extended->new(
        { filename => $defaults->{'config_file'} } );
        # or use its ->inherit() method to overload configurations 

  my $db = $self->{'cfg'}->get_block('db');
  $self->{'dbh'} = MyModule::DB->connect($db);
        # a DBI->connect() object

  # whatever else you need in your constructor

  bless $self, $class;
  return $self;
}

# plus additional methods to process collected data,
# but the code above should render and validate your data 

# Now write a config file looking like this, and your are done

-- conf.d/apps.example.com/signup_form.ini --

[db]
   . . . 


[signup_form]

template=/home/webapps/signup/conf.d/apps.example.com/tmpl/signup_form.tmpl.html
fieldsets=sample_fieldset
title='Signup Form'
submit='Lets Get Started'
header=1
name='signup'
method='post'
debug=0
# debug = 0 | 1 | 2 | 3
reset=1
fieldsubs=1
keepextras=1

;action=$script
;values=\%hash | \@array
;validate=\%hash
;required=[qw()]

[signup_form_sample_fieldset]
fields=this_field,that_field,another_field
process_protocol=sample_data_processing_method
enabled=1

[signup_form_sample_fieldset_this_field]
name=this_field
label='This field'
type=text
fieldset=sample_fieldset
require=1
validate='/\w+/'

[signup_form_sample_fieldset_that_field]
   . . . 

[signup_form_sample_fieldset_another_field]
   . . .

METHODS

->render_web_form('form_name',$debug_level)

Given an object, with a configuration object accessible at $self->{'cfg'}, honoring the ->param() method provided by Config::Simple and Config::Simple::Extended (but possibly others), render the html for a web form for service.

This method takes an option second argument, used to set the debug level. Use 0 or undefined for quiet operation, 1 or greater to see information about the form being built, 2 or greater to watch the field sets being built and 3 or greater to watch the fields being built.

$self->process_form($form)

In your My::Module, you need to write a method for every fieldset.process_protocol in the configuration file.

This method will be called by the ->render_web_form() method and cycle through each fieldset and execute your application specific database interactions and other required processing.

$self->build_fieldset($form,$fieldset,$debug_level)

Parses the configuration object for the fields required to build a form's fieldset and calls ->build_field() to compile the pieces necessary to configure the CGI::FormBuilder $form object.

$self->build_field($form,$fieldset,$field)

Parses the configuration object for the attributes used to configure a CGI::FormBuilder->field() object.

errstr('Error description')

Append its argument, if any, to the error string, and return the result.

AUTHOR

Hugh Esco, <hesco at campaignfoundations.com>

BUGS

Please report any bugs or feature requests to bug-cgi-formbuilder-config-simple at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-FormBuilder-Config-Simple. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

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

perldoc CGI::FormBuilder::Config::Simple

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2010 Hugh Esco.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 dated June, 1991 or at your option any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

A copy of the GNU General Public License is available in the source tree; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.