[Catalyst-commits] r12411 - trunk/examples/CatalystAdvent/root/2009/pen

[frew at dev.catalyst.perl.org]

Author: frew
Date: 2009-12-16 22:36:05 +0000 (Wed, 16 Dec 2009)
New Revision: 12411

Modified:
   trunk/examples/CatalystAdvent/root/2009/pen/dbic-helpers.pod
Log:
polish off most of article

Modified: trunk/examples/CatalystAdvent/root/2009/pen/dbic-helpers.pod
===================================================================
--- trunk/examples/CatalystAdvent/root/2009/pen/dbic-helpers.pod	2009-12-16 22:35:59 UTC (rev 12410)
+++ trunk/examples/CatalystAdvent/root/2009/pen/dbic-helpers.pod	2009-12-16 22:36:05 UTC (rev 12411)
@@ -4,24 +4,26 @@
 
 L<DBIx::Class> is one of the most popular ORM's used in Perl and Catalyst
 development; it is remarkably flexible and useful.  But with all that
-flexibility there is a price that gets paid.  Often things that are super
-short in other ORM's are overly complex in L<DBIx::Class>.
+flexibility there is a price to be paid.  Often things that are concise in other
+ORM's are overly complex in L<DBIx::Class>.
+
 L<DBIx::Class::Helpers> aims at solving many of those problems as succinctly
-as possible.  As our good friend mst would say, it should help you get down to
-the pub sooner than later :-)
+as possible.  As our good friend mst might say, they should allow you to code
+less so you can get down to the pub earlier :-)
 
 So without further ado, I will start with the first, most basic helper...
 
-=head2 Decontextualize
+=head2 IgnoreWantarray
 
-L<DBIx::Class::Helper::Decontextualize> has the longest name of any of the
+L<DBIx::Class::Helper::IgnoreWantarray> has the longest name of any of the
 helpers, but the most basic functionality; all it does is take away the context
 sensitivity of C<< $rs->search >>.  Why would a person ever want to do that?
 I often write code like the following:
 
- $rs = $self->schema->resultset('Parts');
  return $self->sort(
-   $self->paginate($rs)
+   $self->paginate(
+      $self->schema->resultset('Parts')
+   )
  );
 
 Unfortunately, this often means that instead of passing another ResultSet to
@@ -37,20 +39,22 @@
 joining those two sets of items together.  An example could be Users and Roles.
 Users have many Roles; Roles have many Users.  The most "Correct" way to do
 this is with a join table.  I won't go into depth with that here since this is
-is really a survey course, but L<DBIx::Class::Helper::JoinTable> should make
+is really a "survey course", but L<DBIx::Class::Helper::JoinTable> should make
 creating join tables extremely easy.  And because L<DBIx::Class> allows us to
 call C<add_columns> more than once, it's a cinch to have a join table with more
-data in the join than just the relationship.  (An example of when one might
-want that would be an award given from some school.  We have a Person table, a
-School table, an Award table, and a Person_Award table, which should just have
-a join to Person and Award, as well as a date and maybe some other information
-about why the Person deserves this Award.)
+data in the join than just the relationship.
 
+An example of when one might want that would be an award given from some school.
+We have a Student table, a School table, an Award table, and a Student_Award
+table. The last of which should just have a join to Person and Award, as well as
+a date and maybe some other information about why the Person deserves this
+Award.
+
 =head2 Random
 
-L<DBIx::Class::Helper::Random> exists to serve a fairly basic need; to pick
-random rows from a given table.  Currently it will only return a single row,
-but soon, hopefully, L<DBIx::Class> will support the necesary machinations to
+L<DBIx::Class::Helper::Random> exists to serve a fairly basic need: to pick
+random rows from a given table.  Currently it only returns a single row, but
+soon, hopefully, L<DBIx::Class> will support the necessary machinations to
 allow for returning a proper ResultSet of random rows.
 
 =head2 SubClass
@@ -63,14 +67,30 @@
 as well as more complex things, like recreating relationships based on the
 parent class.
 
+The reasoning behind L<DBIx::Class::Helper::SubClass> is that where I work I'd
+like to define a set of tables for Authorization code (Users, Roles,
+Permissions, JoinTables between those, and more) and not have to copy paste the
+definitions to all of our disparate projects.  This helper solves that problem
+quite nicely.  Another reason I could see using this module is when you want to
+define a table without certain columns (TEXT columns come to mind.)  Instead
+of redefining the whole table again with the TEXT columns in another place, you
+might use this helper to subclass the one without the TEXT columns and add TEXT
+columns to the child class.
+
 =head2 VirtualView
 
 L<DBIx::Class::Helper::VirtualView> is probably the most conceptually complex
-of these components.
+of these components.  The purpose is mostly to clean up the returned data from
+a ResultSet.  I won't go into all the gory details here.  For an idea of how it
+works see the POD and tests.
 
 =head2 Extensibility
 
-You could make a better JoinTable, etc.
+In writing these as much as possible I've tried to make parts overrideable in
+the spirit of L<DBIx::Class>.  So for example, if you don't like the way that
+JoinTables have an underscore between table names, you could subclass
+L<DBIx::Class::Helper::JoinTable>, override C<set_table>, and then use your
+subclassed module instead.
 
 =head1 Author