[Dbix-class] docs updated to help dbic beginners

[Hartmaier Alexander]

After talking to Matt (or should i say bombarding him with questions on irc 
*g*) we've come to the conclusion that the docs need better 'newbie support' 
(for people like me) and simply more examples as well.

Here's the svn diff:

*SNIP*
Index: lib/DBIx/Class.pm
===================================================================
--- lib/DBIx/Class.pm	(Revision 233)
+++ lib/DBIx/Class.pm	(Arbeitskopie)
@@ -41,39 +41,41 @@

 =head1 QUICKSTART

-If you're using Class::DBI, replacing
+If you're using Class::DBI and want an easy and fast way of migrating to 
DBIx::Class look at L<DBIx::Class::CDBICompat>!

-  use base qw/Class::DBI/;
+If you're fancy playing around with DBIx::Class from scratch, then read the 
docs
+for DBIx::Class::Table, ::Row, ::Schema, ::DB and ::Relationship,
+and have a look at t/lib/DBICTest.pm for a brief example.

-with
+There are two ways of using DBIx::Class, the 'simple' and the 'schema' one.

-  use base qw/DBIx::Class/;
-  __PACKAGE__->load_components(qw/CDBICompat Core DB/);
+The 'simple' way of using DBIx::Class needs less classes than the 'schema' 
way but doesn't give you the ability to use different database connections.
+Examples where differenct database connections are usefull are:
+- differnt users with different rights
+- different databases at all (production/testing)

-will probably get you started.
+=head2 Simple

-If you're using AUTO_INCREMENT for your primary columns, you'll also want
-yo load the approriate PK::Auto subclass - e.g.
+First you need to create a base class all other classes inherit from.
+Look at L<DBIx::Class::DB> how to do this.

-  __PACKAGE__->load_components(qw/CDBICompat PK::Auto::SQLite Core DB/);
+Next you need to create a class for every table you want to use with 
DBIx::Class.
+Look at L<DBIx::Class::Table> how to do this.

-(with is what ::Test::SQLite does to present the Class::DBI::Test::SQLite
-interface)
+=head2 Schema

-If you fancy playing around with DBIx::Class from scratch, then read the docs
-for DBIx::Class::Table, ::Row, ::Schema, ::DB and ::Relationship,
+With this approach the table classes inherit directly from DBIx::Class::Core 
although it might be a good idea to create a 'parent' class for all table 
classes which inherits from DBIx::Class::Core and adds additional methods 
needed by all table classes, e.g. reading a config file, loading auto primary 
key support.

-  use base qw/DBIx::Class/;
-  __PACKAGE__->load_components(qw/Core DB/);
+Look at L<DBIx::Class::Schema> how to do this.

-and have a look at t/lib/DBICTest.pm for a brief example.
-
 =head1 AUTHOR

 Matt S. Trout <mst at shadowcatsystems.co.uk>

 =head1 CONTRIBUTORS

+Alexander Hartmaier <alexander.hartmaier at t-systems.at>
+
 Andy Grundman <andy at hybridized.org>

 Brian Cassidy <bricas at cpan.org>
Index: lib/DBIx/Class/CDBICompat.pm
===================================================================
--- lib/DBIx/Class/CDBICompat.pm	(Revision 233)
+++ lib/DBIx/Class/CDBICompat.pm	(Arbeitskopie)
@@ -61,6 +61,25 @@
     CDBICompat::MightHave
   /);

+=head1 QUICKSTART
+
+If you're using Class::DBI, replacing
+
+  use base qw/Class::DBI/;
+
+with
+
+  use base qw/DBIx::Class/;
+  __PACKAGE__->load_components(qw/CDBICompat Core DB/);
+
+will probably get you started.
+
+If you're using AUTO_INCREMENT for your primary columns, you'll also want to 
load the approriate PK::Auto subclass - e.g.
+
+  __PACKAGE__->load_components(qw/CDBICompat PK::Auto::SQLite Core DB/);
+
+(with is what ::Test::SQLite does to present the Class::DBI::Test::SQLite 
interface)
+
 =head1 Components

 =over 4
Index: lib/DBIx/Class/DB.pm
===================================================================
--- lib/DBIx/Class/DB.pm	(Revision 233)
+++ lib/DBIx/Class/DB.pm	(Arbeitskopie)
@@ -14,14 +14,13 @@
   package MyDB;

   use base qw/DBIx::Class/;
-  __PACKAGE__->load_components('DB');
+  __PACKAGE__->load_components(qw/Core DB/);

   __PACKAGE__->connection('dbi:...', 'user', 'pass', \%attrs);

   package MyDB::MyTable;

   use base qw/MyDB/;
-  __PACKAGE__->load_components('Core');

   ...

*SNIP*


With best regards
Alexander Hartmaier

T-Systems Austria GesmbH
Rennweg 97-99
A-1030 Vienna


-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/x-pkcs7-signature
Size: 5544 bytes
Desc: not available
Url : http://lists.rawmode.org/pipermail/dbix-class/attachments/20051013/15b457c0/smime.bin