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