NAME

HTML::DBForm - Creates a web interface for updating database tables

SYNOPSIS

   use HTML::DBForm;
   use HTML::DBForm::Search;

   my $editor = HTML::DBForm->new(
       table       => 'contacts',
       primary_key => 'id',
   );

   $editor->element(column => 'email');

   $editor->element(
       label  => 'First Name',
       column => 'fname',
   );

   $editor->element(
       column  => 'interest',
       type    => 'select',
       options => \@list_of_interests
   );

   $editor->element(
       label   => 'Reason for Contact',
       column  => 'reason',
       options => 'select reason from reasons'
   );

   $editor->connect(
       username   => 'webuser',
       password   => 'xxxxxxx',
       datasource => 'dbi:mysql:dbname'
   );

   $search = HTML::DBForm::Search->new('dropdown',
       { columns => ['id', 'lname'] }
   );
  
   $editor->run(search => $search);

INTRODUCTION

HTML::DBForm provides a web interface to insert, update, and delete
rows from a database. This can be used to easily create content editors
for websites, content management systems, or anything that stores its
data in a database.

HTML::DBForm allows easy creation of simple admin screens, but is 
flexable enough to use in many different situations.

METHODS

new

Creates a new editor object.

Required parameters:

table the table we are creating a form to update

primary_key the primary key of this table. Caveat Programmor: There is no checking done to enforce that the column provided as pk is a primary key.

Optional parameters:

stylesheet the URL to a custom stylesheet file.

template the path to a custom template file. To get a template file to start with, you can do this:

perl -MHTML::DBForm -e 'print HTML::DBForm::TEMPLATE()' > sample.tmpl

verbose_errors a boolean parameter that determines whether or not the module displays verbose error messages to the browser, this is set to 0 by default for security reasons.

error_handler a callback that is triggered any time an exception occurs. The callback is passed a list of errors, and the results of the callback are presented as an error message to the user.

Examples

my $editor = HTML::DBForm->new(
        table          => 'table_to_update', 
        primary_key    => 'id',
);


my $editor = HTML::DBForm->new(
        table          => 'table_to_update', 
        primary_key    => 'id', 
        stylesheet     => '/styles/custom.css',
        verbose_errors => 1,
        error_handler  => sub { notify_admin(localtime); return @_ },
);

element

Adds a new element to your editor object. Elements are created as HTML::SuperForm objects

Required parameters:

column the column that this form element represents

Optional parameters:

label a label that will appear next to the form element. this will default to the name of the column.

type the type of form element that will be displayed. Currently, the available options are 'text', 'textarea', 'radio', 'select', 'checkbox', and 'date'. The default is 'text'.

options this is required for elements of type 'radio', 'select', and 'checkbox'. This parameter should hold the values used to create the choice options. This parameter can be one of 4 types of parameters:

scalar: this should be a SQL SELECT statement that returns 2 columns. The first column will be the value, the next will be the label. This SQL statement can SELECT from any table(s).

array: a reference to an array of scalars that will be used as both values and labels

array of arrays: a reference to an array of two-element arrays that will be used to populate the values and labels respectively.

hash: a reference to a hash who's keys will be the HTML element's values, and values will be the HTML element's labels.

Any other parameter pairs will be passed unchanged to the HTML::SuperForm object that creates the actual form element HTML. Please see the HTML::SuperForm Documentation for details. Some common examples are:

disabled => 1, this creates a read-only field.

onclick => "alert('some javascript behavior goes here!'"

size => 50

maxlength => 50

Example

$editor->element( column => 'Name' );

$editor->element( 
    column  => 'sex', 
    type    => 'radio', 
    options => {M => 'Male', F => 'Female'}
);
    
$editor->element( 
    column  => 'color_id',
    label   => 'Product Color'
    type    => 'select', 
    options => 'SELECT id, color FROM colors ORDER BY color'
);

connect

connects to the database.

Required parameters:

dbh a DBI database handle

or

datasource, username, and password

Example

 $editor->connect( dbh => $dbh );
 
 $editor->connect(
     datasource => 'dbi:mysql:my_database',
     username   => 'krailey'
     password   => 'secret'
 );

run

runs the object

Required parameters:

search a DBForm::Search object that will create a search interface for the current table

or

primary_key the value of the primary key for one row that can be updated through the form

Example

 $search = HTML::DBForm::Search->new('dropdown',
     { columns  => ['id', 'name']},
 );
 $editor->run(search => $search);

 $editor->run(primary_key => '1234');

SEE ALSO

HTML::SuperForm HTML::DBForm::Search HTML::DBForm::Search::DropDown HTML::DBForm::Search::TableList

AUTHOR

Ken Railey, <ken_railey@yahoo.com>

COPYRIGHT AND LICENSE

Copyright 2004 by Ken Railey

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

cpanm HTML::DBForm

perl -MCPAN -e shell
install HTML::DBForm