- 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).
- When creating new rows in a table with auto_increment primary keys you need to
- put 'undef' for the key value - this is then removed
- and a correct INSERT statement is generated.
-
- 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.
-
- The support for many to many pseudo relationships should be treated as prototype -
- the DBIC author disagrees with the way I did it.
+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 specify that additional predicate as a second argument to the recursive_update
+method:
+
+ my $user = $restricted_rs->recursive_update( {
+ owned_dvds => [
+ {
+ title => 'One Flew Over the Cuckoo's Nest'
+ }
+ ]
+ },
+ { id => 1 }
+ );
+
+
+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.
+
+=head1 DESIGN CHOICES
+
+=head2 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.