From: Jess Robinson Date: Thu, 30 Mar 2006 17:53:26 +0000 (+0000) Subject: Typo fixups and small documentation expansions X-Git-Tag: v0.06001~16 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=dbsrgits%2FDBIx-Class.git;a=commitdiff_plain;h=4a3c635483dea0ad9c796190397b4c13e5d549f6 Typo fixups and small documentation expansions --- diff --git a/lib/DBIx/Class/Manual.pod b/lib/DBIx/Class/Manual.pod index 19ece79..8d6ea12 100644 --- a/lib/DBIx/Class/Manual.pod +++ b/lib/DBIx/Class/Manual.pod @@ -32,7 +32,7 @@ documentation. It should behave the same way. =head2 L -Listing of existing components, and documentation and example on how to +Existing components, and documentation and example on how to develop new ones. =cut diff --git a/lib/DBIx/Class/Manual/Component.pod b/lib/DBIx/Class/Manual/Component.pod index 330a637..2607e36 100644 --- a/lib/DBIx/Class/Manual/Component.pod +++ b/lib/DBIx/Class/Manual/Component.pod @@ -1,7 +1,14 @@ =head1 NAME -DBIx::Class::Manual::Component - Existing components and how to develop new ones. +DBIx::Class::Manual::Component - Developing DBIx::Class Components + +=head1 WHAT IS A COMPONENT + +A component is a module that can be added in to your DBIx::Class +classes to provide extra functionality. A good example is the PK::Auto +component which automatically retrieves primary keys that the database +itself creates, after the insert has happened. =head1 USING @@ -10,7 +17,7 @@ DBIx::Class classes. package My::Thing; use base qw( DBIx::Class ); - __PACKAGE__->load_components(qw( PK::Auto Core )); + __PACKAGE__->load_components(qw/ PK::Auto Core /); Generally you do not want to specify the full package name of a component, instead take off the DBIx::Class:: part of @@ -18,7 +25,7 @@ it and just include the rest. If you do want to load a component outside of the normal namespace you can do so by prepending the component name with a +. - __PACKAGE__->load_components(qw( +My::Component )); + __PACKAGE__->load_components(qw/ +My::Component /); Once a component is loaded all of it's methods, or otherwise, that it provides will be available in your class. @@ -31,6 +38,45 @@ docs for the components you are using and see if they mention anything about the order in which you should load them. +=head1 CREATING COMPONENTS + +Making your own component is very easy. + + package DBIx::Class::MyComp; + use base qw(DBIx::Class); + # Create methods, accessors, load other components, etc. + 1; + +When a component is loaded it is included in the calling +class' inheritance chain using L. As well as +providing custom utility methods, a component may also +override methods provided by other core components, like +L and others. For example, you +could override the insert and delete methods. + + sub insert { + my $self = shift; + # Do stuff with $self, like set default values. + return $self->next::method( @_ ); + } + + sub delete { + my $self = shift; + # Do stuff with $self. + return $self->next::method( @_ ); + } + +Now, the order that a component is loaded is very important. Components +that are loaded first are the first ones in the inheritance stack. So, if +you override insert() but the DBIx::Class::Row component is loaded first +then your insert() will never be called, since the DBIx::Class::Row insert() +will be called first. If you are unsure as to why a given method is not +being called try printing out the Class::C3 inheritance stack. + + print join ', ' => Class::C3::calculateMRO('YourClass::Name'); + +Check out the L docs for more information about inheritance. + =head1 EXISTING COMPONENTS =head2 Extra @@ -90,45 +136,6 @@ L - Provides a classdata table object and L - Basic row methods. -=head1 CREATEING COMPONENTS - -Making your own component is very easy. - - package DBIx::Class::MyComp; - use base qw(DBIx::Class); - # Create methods, accessors, load other components, etc. - 1; - -When a component is loaded it is included in the calling -class' inheritance chain using L. As well as -providing custom utility methods, a component may also -override methods provided by other core components, like -L and others. For example, you -could override the insert and delete methods. - - sub insert { - my $self = shift; - # Do stuff with $self, like set default values. - return $self->nest::method( @_ ); - } - - sub delete { - my $self = shift; - # Do stuff with $self. - return $self->nest::method( @_ ); - } - -Now, the order that a component is loaded is very important. Components -that are loaded first are the first ones in the inheritance stack. So, if -you override insert() but the DBIx::Class::Row component is loaded first -then your insert() will never be called, since the DBIx::Class::Row insert() -will be called first. If you are unsure as to why a given method is not -being called try printing out the Class::C3 inheritance stack. - - print join ', ' => Class::C3::calculateMRO('YourClass::Name'); - -Check out the L docs for more information about inheritance. - =head1 SEE ALSO L diff --git a/lib/DBIx/Class/Manual/Cookbook.pod b/lib/DBIx/Class/Manual/Cookbook.pod index 1490585..61671d4 100644 --- a/lib/DBIx/Class/Manual/Cookbook.pod +++ b/lib/DBIx/Class/Manual/Cookbook.pod @@ -489,6 +489,13 @@ C. $class->next::method($attrs); } +For more information about C, look in the L +documentation. See also L for more +ways to write your own base classes to do this. + +People looking for ways to do "triggers" with DBIx::Class are probably +just looking for this. + =head2 Stringification Employ the standard stringification technique by using the C