[Dbix-class] FAQ patch about stringification

[Matt S Trout]

Marcello Romani wrote:
> I have written a small paragraph that clarifies (I hope :-) why DBIC has 
> no "stringify_self" method or "Stringify" column group.
> 
> This obviously intended for DBIC newcomers coming from CDBI...
> 
> 
> ------------------------------------------------------------------------
> 
> --- FAQ.pod	2006-08-18 13:00:27.000000000 +0200
> +++ FAQ_modified.pod	2006-09-07 12:09:23.000000000 +0200
> @@ -324,3 +324,43 @@
>  you ask the resultset for an actual row object.
>  
>  =back
> +
> +=head2 Notes for CDBI users
> +
> +=over 4
> +
> +=item Is there a way to make an object auto-stringify itself as a particular column or group of columns (a-la cdbi Stringfy column group, or stringify_self method) ?
> +
> +Perl already offers a method to make an object stringify itself, through the C<use overload> pragma.
> +
> +Therefore there is no need for a specialized stringification method like C<stringify_self>.
> +
> +B<Quick example:>
> +
> +   use overload "" => sub { $_[0]->name . ", " . $_[0]->address }
> +
> +
> +B<Scenario:>
> +
> +Suppose we have two tables: C<Product> and C<Category>. The table specifications are:
> +
> +  Product(id, Description, category)
> +  Category(id, Description)
> +
> +C<category> is a foreign key into the Category table.
> +
> +If you have a Product object C<$obj> and write something like
> +
> +  print $obj->category
> +
> +things will not work as expected.
> +
> +To obtain, for example, the category description, you should add this method to the class mapping the Category table (tipically C<DB::Main::Category>):
> +
> +  use overload "" => sub {
> +      my $self = shift;
> +
> +      return $self->Description;
> +  }
> +
> +=back

There's already a rather more minimal entry at

http://search.cpan.org/dist/DBIx-Class/lib/DBIx/Class/Manual/Cookbook.pod#Stringification

Maybe merge the better description into the cookbook and create a simpler FAQ 
entry that links to it?

Anybody got any better ideas?

-- 
      Matt S Trout       Offering custom development, consultancy and support
   Technical Director    contracts for Catalyst, DBIx::Class and BAST. Contact
Shadowcat Systems Ltd.  mst (at) shadowcatsystems.co.uk for more information

+ Help us build a better perl ORM: http://dbix-class.shadowcatsystems.co.uk/ +