updated readme
[chaz/p5-DBIx-Class-ResultSet-RecursiveUpdate] / README
1 NAME
2 DBIx::Class::ResultSet::RecursiveUpdate - like update_or_create - but
3 recursive
4
5 VERSION
6 This document describes DBIx::Class::ResultSet::RecursiveUpdate version
7 0.006
8
9 SYNOPSIS
10 The functional interface:
11
12 my $new_item = DBIx::Class::ResultSet::RecursiveUpdate::Functions::recursive_update({
13 resultset => $schema->resultset( 'Dvd' ),
14 updates => {
15 id => 1,
16 owned_dvds => [
17 {
18 title => 'One Flew Over the Cuckoo's Nest'
19 }
20 ]
21 }
22 });
23
24 As ResultSet subclass:
25
26 __PACKAGE__->load_namespaces( default_resultset_class => '+DBIx::Class::ResultSet::RecursiveUpdate' );
27
28 in the Schema file (see t/lib/DBSchema.pm). Or appriopriate 'use base'
29 in the ResultSet classes.
30
31 Then:
32
33 my $user = $user_rs->recursive_update( {
34 id => 1,
35 owned_dvds => [
36 {
37 title => 'One Flew Over the Cuckoo's Nest'
38 }
39 ]
40 }
41 );
42
43 DESCRIPTION
44 This is still experimental. I've added a functional interface so that it can be used
45 in Form Processors and not require modification of the model.
46 You can feed the ->create method with a recursive datastructure and have
47 the related records created. Unfortunately you cannot do a similar thing
48 with update_or_create - this module tries to fill that void.
49
50 It is a base class for ResultSets providing just one method:
51 recursive_update which works just like update_or_create but can
52 recursively update or create data objects composed of multiple rows. All
53 rows need to be identified by primary keys - so you need to provide them
54 in the update structure (unless they can be deduced from the parent row
55 - for example when you have a belongs_to relationship). If not all
56 colums comprising the primary key are specified - then a new row will be
57 created, with the expectation that the missing columns will be filled by
58 it (as in the case of auto_increment primary keys).
59
60 If the resultset itself stores an assignement for the primary key, like
61 in the case of:
62
63 my $restricted_rs = $user_rs->search( { id => 1 } );
64
65 then you need to inform recursive_update about additional predicate with
66 a second argument:
67
68 my $user = $restricted_rs->recursive_update( {
69 owned_dvds => [
70 {
71 title => 'One Flew Over the Cuckoo's Nest'
72 }
73 ]
74 },
75 [ 'id' ]
76 );
77
78 This will work with a new DBIC release.
79
80 For a many_to_many (pseudo) relation you can supply a list of primary
81 keys from the other table - and it will link the record at hand to those
82 and only those records identified by them. This is convenient for
83 handling web forms with check boxes (or a SELECT box with multiple
84 choice) that let you update such (pseudo) relations.
85
86 For a description how to set up base classes for ResultSets see
87 load_namespaces in DBIx::Class::Schema.
88
89 DESIGN CHOICES
90 Treatment of many to many pseudo relations
91 The function gets the information about m2m relations from
92 DBIx::Class::IntrospectableM2M. If it is not loaded in the ResultSource
93 classes - then the code relies on the fact that: if($object->can($name)
94 and !$object->result_source->has_relationship($name) and $object->can(
95 'set_' . $name ) )
96
97 then $name must be a many to many pseudo relation. And that in a
98 similarly ugly was I find out what is the ResultSource of objects from
99 that many to many pseudo relation.
100
101 INTERFACE
102 METHODS
103 recursive_update
104 The method that does the work here.
105
106 is_m2m
107 $self->is_m2m( 'name ' ) - answers the question if 'name' is a many to
108 many (pseudo) relation on $self.
109
110 get_m2m_source
111 $self->get_m2m_source( 'name' ) - returns the ResultSource linked to by
112 the many to many (pseudo) relation 'name' from $self.
113
114 DIAGNOSTICS
115 CONFIGURATION AND ENVIRONMENT
116 DBIx::Class::RecursiveUpdate requires no configuration files or
117 environment variables.
118
119 DEPENDENCIES
120 DBIx::Class
121
122 INCOMPATIBILITIES
123 None reported.
124
125 BUGS AND LIMITATIONS
126 No bugs have been reported.
127
128 Please report any bugs or feature requests to
129 "bug-dbix-class-recursiveput@rt.cpan.org", or through the web interface
130 at <http://rt.cpan.org>.
131
132 AUTHOR
133 Zbigniew Lukasiak "<zby@cpan.org>" Influenced by code by Pedro Melo.
134
135 LICENCE AND COPYRIGHT
136 Copyright (c) 2008, Zbigniew Lukasiak "<zby@cpan.org>". All rights
137 reserved.
138
139 This module is free software; you can redistribute it and/or modify it
140 under the same terms as Perl itself. See perlartistic.
141
142 DISCLAIMER OF WARRANTY
143 BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
144 FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
145 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
146 PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
147 EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
148 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
149 ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
150 YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
151 NECESSARY SERVICING, REPAIR, OR CORRECTION.
152
153 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
154 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
155 REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
156 TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
157 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
158 SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
159 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
160 FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
161 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
162 DAMAGES.
163
This page took 0.037974 seconds and 5 git commands to generate.