X-Git-Url: https://git.dogcows.com/gitweb?p=chaz%2Fp5-DBIx-Class-ResultSet-RecursiveUpdate;a=blobdiff_plain;f=README;h=8a741c9ae5fb210d0ff236da08728736dcebc6dc;hp=7802081f05585e227e7fd2bb2d3aba02e9bda73f;hb=6ce63ba71e40f5b301e32a3ade6d70f67948ee10;hpb=424363ed169eae916480670bea2363322285855a diff --git a/README b/README index 7802081..8a741c9 100644 --- a/README +++ b/README @@ -1,38 +1,159 @@ -DBIx-Class-RecursiveUpdate version 0.0.1 +NAME + DBIx::Class::ResultSet::RecursiveUpdate - like update_or_create - but + recursive -[ REPLACE THIS... +SYNOPSIS + The functional interface: - The README is used to introduce the module and provide instructions on - how to install the module, any machine dependencies it may have (for - example C compilers and installed libraries) and any other information - that should be understood before the module is installed. + my $new_item = DBIx::Class::ResultSet::RecursiveUpdate::Functions::recursive_update({ + resultset => $schema->resultset( 'Dvd' ), + updates => { + id => 1, + owned_dvds => [ + { + title => 'One Flew Over the Cuckoo's Nest' + } + ] + } + }); - A README file is required for CPAN modules since CPAN extracts the - README file from a module distribution so that people browsing the - archive can use it get an idea of the modules uses. It is usually a - good idea to provide version information here so that people can - decide whether fixes for the module are worth downloading. -] + As ResultSet subclass: + __PACKAGE__->load_namespaces( default_resultset_class => '+DBIx::Class::ResultSet::RecursiveUpdate' ); -INSTALLATION + in the Schema file (see t/lib/DBSchema.pm). Or appriopriate 'use base' + in the ResultSet classes. -To install this module, run the following commands: + Then: - perl Makefile.PL - make - make test - make install + my $user = $user_rs->recursive_update( { + id => 1, + owned_dvds => [ + { + title => 'One Flew Over the Cuckoo's Nest' + } + ] + } + ); +DESCRIPTION +This is still experimental. I've added a functional interface so that it can be used +in Form Processors and not require modification of the model. + You can feed the ->create method with a recursive datastructure and have + the related records created. Unfortunately you cannot do a similar thing + with update_or_create - this module tries to fill that void. + + It is a base class for ResultSets providing just one method: + recursive_update which works just like update_or_create but can + recursively update or create data objects composed of multiple rows. All + rows need to be identified by primary keys - so you need to provide them + in the update structure (unless they can be deduced from the parent row + - for example when you have a belongs_to relationship). If not all + colums comprising the primary key are specified - then a new row will be + created, with the expectation that the missing columns will be filled by + it (as in the case of auto_increment primary keys). + + If the resultset itself stores an assignement for the primary key, like + in the case of: + + my $restricted_rs = $user_rs->search( { id => 1 } ); + + then you need to inform recursive_update about additional predicate with + a second argument: + + my $user = $restricted_rs->recursive_update( { + owned_dvds => [ + { + title => 'One Flew Over the Cuckoo's Nest' + } + ] + }, + [ 'id' ] + ); + + This will work with a new DBIC release. + + For a many_to_many (pseudo) relation you can supply a list of primary + keys from the other table - and it will link the record at hand to those + and only those records identified by them. This is convenient for + handling web forms with check boxes (or a SELECT box with multiple + choice) that let you update such (pseudo) relations. + + For a description how to set up base classes for ResultSets see + load_namespaces in DBIx::Class::Schema. + +DESIGN CHOICES + Treatment of many to many pseudo relations + The function gets the information about m2m relations from + DBIx::Class::IntrospectableM2M. If it is not loaded in the ResultSource + classes - then the code relies on the fact that: if($object->can($name) + and !$object->result_source->has_relationship($name) and $object->can( + 'set_' . $name ) ) + + then $name must be a many to many pseudo relation. And that in a + similarly ugly was I find out what is the ResultSource of objects from + that many to many pseudo relation. + +INTERFACE +METHODS + recursive_update + The method that does the work here. + + is_m2m + $self->is_m2m( 'name ' ) - answers the question if 'name' is a many to + many (pseudo) relation on $self. + + get_m2m_source + $self->get_m2m_source( 'name' ) - returns the ResultSource linked to by + the many to many (pseudo) relation 'name' from $self. + +DIAGNOSTICS +CONFIGURATION AND ENVIRONMENT + DBIx::Class::RecursiveUpdate requires no configuration files or + environment variables. DEPENDENCIES + DBIx::Class + +INCOMPATIBILITIES + None reported. + +BUGS AND LIMITATIONS + No bugs have been reported. + + Please report any bugs or feature requests to + "bug-dbix-class-recursiveput@rt.cpan.org", or through the web interface + at . + +AUTHOR + Zbigniew Lukasiak "" Influenced by code by Pedro Melo. -None. +LICENCE AND COPYRIGHT + Copyright (c) 2008, Zbigniew Lukasiak "". 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. -COPYRIGHT AND LICENCE +DISCLAIMER OF WARRANTY + BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY + FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN + OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES + PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER + EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED + WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE + ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH + YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL + NECESSARY SERVICING, REPAIR, OR CORRECTION. -Copyright (C) 2008, Zbigniew Lukasiak + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING + WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR + REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE + TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR + CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE + SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING + RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A + FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF + SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH + DAMAGES. -This library is free software; you can redistribute it and/or modify -it under the same terms as Perl itself.