NAME

DBIx::AsForm - Generate an HTML form from a database table.

SYNOPSIS

Generate an HTML form a database table in a flexible way.

Setup:

    use DBIx::AsForm;
    my $daf = DBIx::AsForm->new($dbh);

Generate an empty form:

    my @html_form = $daf->to_html_array('widgets');

    use CGI;
    my $q = CGI->new();
    print $q->start_form;
        for my $href (@html_form) {
            print "<b>$href->{name}</b>: ". $href->{obj}->as_HTML." <br>"
        }
    print $q->end_form;

MOTIVATION

This project was borne out of combined excitement and frustration with Class::DBI::AsForm. I like the general design of the module because it doesn't try to do too much. However, I don't use Class::DBI as part of my standard development, and I didn't want to depend on Class::DBI for this tool.

I also wanted smarter form element generation than Class::DBI::AsForm provides. Over time I expect Class::DBI::AsForm to improve in this area to match the advances I've made in that area.

METHODS

new()

  my $daf = DBIx::AsForm->new($dbh);

Creates a new DBIx::AsForm object. The first argument must be an existing database handle.

to_html_array()

   # simple syntax 
   my @html_form = $daf->to_html_array($table_name);

   # More flexible
   my @html_form = $daf->to_html_array(
    table     => $table, 
    row_href  => \%row,          # optional
    columns   => \@column_names, # optional, defaults to all
    stringify => {               # optional
        widget.id => 'widget_name'
    },
   );

This returns an array of hashrefs mapping all the column names of the table to HTML::Element objects representing form widgets.

An array is used to preserve the proper ordering.

Optionally, a hashref of data an be passed in to populate the form elements.

A list of column names to use can be provided. The default is to use all of them in the order DBI returns them.

Finally, 'stringify'. We will detect all the "has a" foreign key relationships automatically. However, usually these are ID columns when we want to display a name. Use stringify to define another column name from the other table to display in place of the ID. By default we will just display the ID. A future version will support a callback here to define more complex stringification possibilities.

to_html_href()

The same as to_html_array(), but returns the results in a single hashref.

INTERNALS

The details are subject to change without notice and are documented here solely for the benefit of contributors to this module.

_to_field($column_info_row_href)

  my $href = _to_field($column_info_row_href);
  
  # Example contents of $href
  { name => 'widget', obj => $a };

This maps an individual column to a form element. The input is expected to be a hashref as would be returned in as an array element from a call to DBI's column_info().

The output is a hashref with 'name' and 'obj' keys to hold the column name and a HTML::Element object.

_decide_col_details()

  ($input_type, $attr_href ) = $self->_decide_col_details($row_href);

Returns a suggested HTML form element type and an attribute of form tag attributes based on a hashref of column meta data, as supplied by DBI's column_info().

SEE ALSO

Class::DBI::AsForm - The same idea, integrated with Class::DBI

HTML::FormEngine::DBSQL - It has similiar functionality, but is difficult to use and customize if you don't want the other functionality.

DB_Browser - http://www.summersault.com/sofware/db_browser - The oldest automated database to form tool I'm aware of. The code looks old school now, but still has some useful nuggest of wisdom about database meta data.

TODO

 * Testing generally isn't done
 * Foreign key stuff is broken
 * Test with more databases besides PostgreSQL
 * Set a max size limit on the textareas
 * Consider smarter date fields types, perhaps integrate
   with one of the JavaScript calendar date-picker things.
 * Possible tab-completion for has-a relationships with big
   tables (via AJAX). 
 * Address underlying issue that HTML::Element doesn't always produce
   valid HTML/XHTML

BUGS

please report any bugs or feature requests to c<bug-dbix-asform@rt.cpan.org>, or through the web interface at l<http://rt.cpan.org/noauth/reportbug.html?queue=dbix-asform>. i will be notified, and then you'll automatically be notified of progress on your bug as i make changes.

CONTRIBUTING

Patches, questions and feedback are welcome. This project is managed using the darcs source control system ( http://www.darcs.net/ ). My darcs archive is here: http://mark.stosberg.com/darcs_hive/as_form/

AUTHOR

Mark Stosberg, c<< <mark@summersault.com> >>

Acknowledgements

Copyright & License

copyright 2005 Mark Stosberg, all rights reserved.

this program is free software; you can redistribute it and/or modify it under the same terms as perl itself.

cpanm DBIx::AsForm

perl -MCPAN -e shell
install DBIx::AsForm