DBIx::Class::FormTools - Helper module for building forms with multiple related DBIx::Class objects.
This document describes DBIx::Class::FormTools version 0.0.11
There may be bugs. The interface might change (But the it hasn't changed in a long time, so it is probably safe to use).
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.
Film
Actor
Role
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');
use DBIx::Class::FormTools; my $formtool = DBIx::Class::FormTools->new({ schema => $schema });
<%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="<% $formtool->fieldname($film, 'title', 'o1') %>" type="text" value="<% $film->title %>" /> <input name="<% $formtool->fieldname($film, 'length', 'o1') %>" type="text" value="<% $film->length %>" /> <input name="<% $formtool->fieldname($film, 'comment', 'o1') %>" type="text" value="<% $film->comment %>" /> <input name="<% $formtool->fieldname($actor, 'name', 'o2') %>" type="text" value="<% $actor->name %>" /> <input name="<% $formtool->fieldname($role, undef, 'o3', { film_id => 'o1', actor_id => 'o2' }) %>" type="hidden" value="dummy" /> </form>
my @objects = $formtool->formdata_to_objects(\%querystring); foreach my $object ( @objects ) { # Assert and Manupulate $object as you like $object->insert_or_update; }
DBIx::Class::FormTools is a data serializer, that can convert HTML formdata to DBIx::Class objects based on element names created with DBIx::Class::FormTools.
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.
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".
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.
object_id
new
Arguments: { schema => $schema }
Creates new form helper
my $formtool = DBIx::Class::FormTools->new({ schema => $schema });
schema
Arguments: None
Returns the schema
my $schema = $formtool->schema;
fieldname
Arguments: $object, $accessor, $object_id, $foreign_object_ids
my $name_film = $formtool->fieldname($film, 'title', 'o1'); my $name_actor = $formtool->fieldname($actor, 'name', 'o2'); my $name_role = $formtool->fieldname($role, undef,'o3', { film_id => 'o1', actor_id => 'o2' } ); my $name_role = $formtool->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.
HASHREF
attribute => object_id
formdata_to_object_hash
Arguments: \%formdata
my @objects = $formtool->formdata_to_objects($formdata);
Turn formdata(a querystring) in the form of a HASHREF into an HASHREF of DBIx::Class objects indexed by object_id.
DBIx::Class
formdata_to_objects
Turn formdata(a querystring) in the form of a HASHREF into an ARRAY of DBIx::Class objects.
ARRAY
This is a method which provides access to the current class's metaclass.
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.
DBIx::Class::Row->create()
primary key
create
insert
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.
DBIx::Class::PK::Auto
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.
bug-dbix-class-formtools@rt.cpan.org
David Jack Olrik <djo@cpan.org>
<djo@cpan.org>
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 perlartistic.
Add form object, that keeps track of object ids automagickly.
Add field generator, that can generate HTML/XHTML fields based on the objects in the form object.
DBIx::Class DBIx::Class::PK::Auto
To install DBIx::Class::FormTools, copy and paste the appropriate command in to your terminal.
cpanm
cpanm DBIx::Class::FormTools
CPAN shell
perl -MCPAN -e shell install DBIx::Class::FormTools
For more information on module installation, please visit the detailed CPAN module installation guide.