DBIx::Class::FormTools - Helper module for building forms with multiple related L<DBIx::Class> objects.

NAME

DBIx::Class::FormTools - Helper module for building forms with multiple related the DBIx::Class manpage objects.

VERSION

This document describes DBIx::Class::FormTools version 0.0.5

SYNOPSIS

This is ALPHA software

There may be bugs. The interface may change. Do not use this for anything important just yet.

Prerequisites

In the examples I use 3 objects, a Film, an Actor and a Role. Role is a many to many relation between Film and Actor.

    package MySchema;
    use base 'DBIx::Class::Schema';
    __PACKAGE__->load_classes(qw[
        Film
        Actor
        Role
    ]);
    package MySchema::Film;
    __PACKAGE__->table('films');
    __PACKAGE__->add_columns(qw[
        id
        title
    ]);
    __PACKAGE__->set_primary_key('id');
    __PACKAGE__->has_many(roles => 'MySchema::Role', 'film_id');
    package MySchema::Actor;
    __PACKAGE__->table('films');
    __PACKAGE__->add_columns(qw[
        id
        name
    ]);
    __PACKAGE__->set_primary_key('id');
    __PACKAGE__->has_many(roles => 'MySchema::Role', 'actor_id');
    package MySchema::Role;
    __PACKAGE__->table('roles');
    __PACKAGE__->add_columns(qw[
        film_id
        actor_id
    ]);
    __PACKAGE__->set_primary_key(qw[
        film_id
        actor_id
    ]);
    __PACKAGE__->belongs_to(film_id  => 'MySchema::Film');
    __PACKAGE__->belongs_to(actor_id => 'MySchema::Actor');

In your Controller

    use DBIx::Class::FormTools;
    
    my $helper = DBIx::Class::FormTools->({ schema => $schema });

In your view - the HTML::Mason manpage example

    <%init>
    my $film  = $schema->resultset('Film')->find(42);
    my $actor = $schema->resultset('Actor')->find(24);
    my $role  = $schema->resultset('Role')->new;
    
    </%init>
    <form>
        <input
            name="<% $helper->fieldname($film, 'title', 'o1') %>"
            type="text"
            value="<% $film->title %>"
        />
        <input
            name="<% $helper->fieldname($film, 'length', 'o1') %>"
            type="text"
            value="<% $film->length %>"
        />
        <input
            name="<% $helper->fieldname($film, 'comment', 'o1') %>"
            type="text"
            value="<% $film->comment %>"
        />
        <input
            name="<% $helper->fieldname($actor, 'name', 'o2') %>"
            type="text"
            value="<% $actor->name %>"
        />
        <input
            name="<% $helper->fieldname($role, undef, 'o3', {
                film_id  => 'o1',
                actor_id => 'o2'
            }) %>"
            type="hidden"
            value="dummy"
        />
    </form>

In your controller (or cool helper module, used in your controller)

    my @objects = $helper->formdata_to_objects(\%querystring);
    foreach my $object ( @objects ) {
        # Assert and Manupulate $object as you like
        $object->insert_or_update;
    }

DESCRIPTION

Introduction

the DBIx::Class::FormTools manpage is a data serializer, that can convert HTML formdata to the DBIx::Class manpage objects based on element names created with the DBIx::Class::FormTools manpage.

It uses user supplied object ids to connect the objects with each-other. The objects do not need to exist on beforehand.

The module is not ment to be used directly, although it can of-course be done as seen in the above example, but rather used as a utility module in a Catalyst helper module or other equivalent framework.

Connecting the dots - The problem at hand

Creating a form with data from one object and storing it in a database is easy, and several modules that does this quite well already exists on CPAN.

What I am trying to accomplish here, is to allow multiple objects to be created and updated in the same form - This includes the relations between the objects i.e. ``connecting the dots''.

Non-existent ids - Enter object_id

When converting the formdata to objects, we need ``something'' to identify the objects by, and sometimes we also need this ``something'' to point to another object in the formdata to signify a relation. For this purpose we have the object_id which is user definable and can be whatever you like.

METHODS

new

Arguments: { schema => $schema }

Creates new form helper

    my $helper = DBIx::Class::FormTools->new({ schema => $schema });

schema

Arguments: None

Returns the schema

    my $helper = $helper->schema;

fieldname

Arguments: $object, $accessor, $object_id, $foreign_object_ids

    my $name_film  = $helper->fieldname($film, 'title', 'o1');
    my $name_actor = $helper->fieldname($actor, 'name', 'o2');
    my $name_role  = $helper->fieldname($role, undef,'o3',
        { film_id => 'o1', actor_id => 'o2' }
    );
    my $name_role  = $helper->fieldname($role,'charater','o3',
        { film_id => 'o1', actor_id => 'o2' }
    );

Creates a unique form field name for use in an HTML form.

$object
The object you wish to create a key for.

$accessor
The attribute in the object you wish to create a key for.

$object_id
A unique string identifying a specific object in the form.

$foreign_object_ids
A HASHREF containing attribute => object_id pairs, use this to connect objects with each-other as seen in the above example.

formdata_to_objects

Arguments: \%formdata

    my @objects = $helper->formdata_to_objects($formdata);

Turn formdata(a querystring) in the form of a HASHREF into an ARRAY of DBIx::Class objects.

meta

This is a method which provides access to the current class's metaclass.

CAVEATS

Transactions

When using this module it is prudent that you use a database that supports transactions.

The reason why this is important, is that when calling formdata_to_objects, DBIx::Class::Row->create() is called foreach nonexistent object in order to get the primary key filled in. This call to create results in a SQL insert statement, and might leave you with one object successfully put into the database and one that generates an error - Transactions will allow you to examine the ARRAY of objects returned from formdata_to_objects before actually storing them in the database.

Automatic Primary Key generation

You must use DBIx::Class::PK::Auto, otherwise the formdata_to_objects will fail when creating new objects, as it is unable to determine the value for the primary key, and therefore is unable to connect the object to any related objects in the form.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-dbix-class-formtools@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

David Jack Olrik <djo@cpan.org>

LICENCE AND COPYRIGHT

Copyright (c) 2006, David Jack Olrik <djo@cpan.org>. All rights reserved.

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

TODO

SEE ALSO

the DBIx::Class manpage the DBIx::Class::PK::Auto manpage

 DBIx::Class::FormTools - Helper module for building forms with multiple related L<DBIx::Class> objects.