The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Form-Sensible-Reflector-MySQL-0.7
River stage zero No dependents
++
/ Form::Sensible::Reflector::MySQL

NAME

Form::Sensible::Reflector::MySQL - Create a Form::Sensible object from a MySQL schema

SYNOPSIS

        use Form::Sensible;
        use Form::Sensible::Reflector::MySQL;
        my $reflector = ReflectorMySQL->new();
        my $form  = $reflector->reflect_from($dbh, 
                {
                        form_name => $table_name,
                        information_schema_dbh => DBI->connect(
                                'DBI:mysql:database=information_schema;host=localhost', 'root', 'password',
                        ),
                        # populate => 1,
                        # only_columns => [qw[ id forename surname dob ] ],
                }
        );
        $form->add_field(
                Form::Sensible::Field::Toggle->new( 
                        name => 'Submit form',
                )
        );
        my $renderer = Form::Sensible->get_renderer('HTML');
        my $html     = $renderer->render($form)->complete;
        exit;

DESCRIPTION

This module provides to Form::Sensible the ability to simply create from MySQL tables forms whose fields and validators reflect the schema of the database table. Forms can be created empty, or from the value of a specified row. Joins are not supported.

ALPHA SOFTWARE

This module is to be considered a pre-release, to gather test feedback and suggestions. It should not be considered stable for a production environment, and its implementation is subject to change.

Specifically, type checking of large numberics (specifically doubles) is not well tested, and Select fields (for ENUM and SET) seems to require some updating of Form::Sensible itself.

REPRESENTATION OF THE SCHEMA

FIELD NAMES

Field names are taken from column names, or can be taken from column comments (see "information_schema_dbh" under "reflect_form").

REQUIRED FIELDS

Fields are marked as required if their database definition contains NOT NULL.

DEFAULT VALUES

Default values are, by default, taken from the database - see "no_db_defaults", below "reflect_from".

FIELD TYPES

String and numeric types are mapped to the appropriate Form::Sensible::Field types, with the exceptions described below.

NB Numeric fields may only contain numbers with decimal points (.) but not commas. This outght to be locale dependant, but as far as I can tell, MySQL only accepts data in this format (http://dev.mysql.com/doc/refman/5.0/en/locale-support.html).

ENUM AND SET

Set and enumeration columns are rendered as Select fields.

BOOLEAN TYPES

Boolean fields (Form::Sensible::Field::Toggle) are expected to be defined in the SQL schema as BIT(1) columns, based on the rationale outlined in comments on the MySQL website (http://dev.mysql.com/doc/refman/5.0/en/numeric-types.html).

NB This is in contradiction to the MySQL behaviour of interpreting the declaration of BOOLEAN columns as TINYINT(1). Support for the latter could be added as a Toggle field, but what would a NULL entry signfiy?

The generated Form::Sensible::Field::Toggle has on_value an off_value of 1 an 0, respectively.

BLOB-TYPE COLUMNS

These are currently converted to Text and LongText fields. That can of course be changed by the user after the form as been created, but I am open to suggestions on how to better handle them.

TRIGGER

No Form::Sensible::Field::Trigger is added to the form. See the SYNOPSIS, above.

INTERNATIONALISATION

See lang under "reflect_from".

METHODS

reflect_form

        ReflectorMySQL->new->reflect_from( $dbh, $options );

Creates a form from a MySQL table schema, optionally populating it with data from the table.

In the above example, $dbh is a connected database handle, and $options a reference to a hash as follows:

form_name

In keeping with Form::Sensible::Reflector, this field can hold the name of the table, though that will be over-ridden by any value in table_name.

table_name

The name of the table upon which to reflect, if not supplied in form_name.

no_db_defaults

Optinal. If a true value, will cancel the default behaviour of populating the empty form with any DEFAULT values set in the schema (aside from CURRENT_TIMESTAMP.

only_columns

An anonymous list of the names of columns to use, to override the default behaviour of using all columns.

populate

Optional. If supplied, causes the created form to be populated with data from a row in the table. The value of populate should be a reference to a hash that defines column names and values to be used in the selection of a record. No error checking is performed.

information_schema_dbh

Optional DBH connected to the information_schema database. If supplied, each field's display_name will be set from the COMMENT recorded in the table definition, if available.

Field comments are created thus:

        CREATE TABLE foo (  
                forename VARCHAR(255) NOT NULL COMMENT 'First name'  
        )

        ALTER TABLE foo CHANGE COLUMN forename  
                forename VARCHAR(255) NOT NULL COMMENT 'Forename'

Comments can be viewed with SHOW CREATE foo or as follows:

        mysql5> USE information_schema;
        mysql5> SELECT column_name, column_comment FROM COLUMNS WHERE table_name='foo';

Should Form::Sensible::Form one day support a display_name attribute, this method could supply it with the table's COMMENT: at present, that value is stored in the form_display_name field of the caller.

lang

Defines the language of error messages that are not over-rideable using the default means supplied by Form::Sensible. The format should be that used by HTML, as described at http://www.w3.org/International/articles/language-tags/, without hyphenation.

The default language is enGB. To use another language, supply another string, and use it to create a namespace such as Form::Sensible::Reflector::MySQL::I18N::enGB that contains hash reference called $I18N. Please see the bottom of this file's source code for the required keys.

EXPORTS

None.

get_fieldnames

Private method inherited from Form::Sensible::Reflector.

DEPENDENCIES

Moose, Form::Sensible::Reflector, Form::Sensible, DBD::mysql, DateTime::Format::MySQL, Math::BigInt.

CAVEAT EMPTORIUM

  • The Math::Big* modules may help if you use numbers.

  • At the time of writing, the young Form::Sensible::Field::Select has a bug which prevents the correct setting of the selected entity, as well as preventing multiple selections. This has been reported and will be fiex in the next release.

  • Numeric fields may not contain commas, as described under "FIELD TYPES".

BUGS, PATCHES, SUGGESTIONS

Please make use of CPAN's Request Tracker.

SEE ALSO

The MySQL Manual, Chater 10 Data Types.

Form::Sensible, Form::Sensible::Reflector, Form::Sensible::Reflector::DBIC, Form::Sensible::Field.

AUTHOR AND COPYRIGHT

Copyright (C) Lee Goddard, 2010-2011. All Rights Reserved.

Made available under the same terms as Perl.

NAME

Form::Sensible::Reflector::MySQL::I18N::enGB - error messages

DESCRIPTION

This namesapce provides the default error messages for form validation as described in "INTERNATIONALISATION" in Form::Sensible::Reflector::MySQL.

AUTHOR AND COPYRIGHT

Copyright (C) Lee Goddard, 2010-2011. All Rights Reserved.

Made available under the same terms as Perl.