X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FManual%2FComponent.pod;h=dfa9f94581e53cfac2b1100d115b82f37cd29d80;hb=1b6fe47d369e84831a8a881813a53cca68694e72;hp=1dfe90d03137e26f8095ef34693858a9bdaaf693;hpb=3d18a9c1993fb77df13803ad30978c590fb872e4;p=dbsrgits%2FDBIx-Class.git diff --git a/lib/DBIx/Class/Manual/Component.pod b/lib/DBIx/Class/Manual/Component.pod index 1dfe90d..dfa9f94 100644 --- a/lib/DBIx/Class/Manual/Component.pod +++ b/lib/DBIx/Class/Manual/Component.pod @@ -1,142 +1,139 @@ =head1 NAME -DBIx::Class::Manula::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 -Components are loaded using the load_components() method within your +Components are loaded using the load_components() method within your DBIx::Class classes. package My::Thing; - use base qw( DBIx::Class ); - __PACKAGE__->load_components(qw( PK::Auto Core )); + use base qw( DBIx::Class::Core ); + __PACKAGE__->load_components(qw/InflateColumn::DateTime TimeStamp/); -Generally you do not want to specify the full package name -of a component, instead take off the DBIx::Class:: part of -it and just include the rest. If you do want to load a -component outside of the normal namespace you can do so +Generally you do not want to specify the full package name +of a component, instead take off the DBIx::Class:: part of +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, +Once a component is loaded all of it's methods, or otherwise, that it provides will be available in your class. -The order in which is you load the components may be -very imporant, depending on the component. The general -rule of thumb is to first load extra components and then -load core ones last. If you are not sure, then read the -docs for the components you are using and see if they -mention anything about the order in which you should load -them. +The order in which is you load the components may be very +important, depending on the component. If you are not sure, +then read the docs for the components you are using and see +if they mention anything about the order in which you should +load them. -=head1 EXISTING +=head1 CREATING COMPONENTS -=head2 Extra +Making your own component is very easy. -These components provide extra functionality above -and beyond what any normal user would need out of the -box. + package DBIx::Class::MyComp; + use base qw(DBIx::Class); + # Create methods, accessors, load other components, etc. + 1; -L - Class::DBI Compatability layer. +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. -L - Retrieve automatically created primary keys upon insert. + 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 + +These components provide extra functionality beyond +basic functionality that you can't live without. + +L - Class::DBI Compatibility layer. L - Build forms with multiple interconnected objects. L - Like FromForm but with DBIx::Class and HTML::Widget. +L - Modify the position of objects in an ordered list. + +L - Retrieve automatically created primary keys upon insert. + L - Display the amount of time it takes to run queries. L - Declare virtual columns that return random strings. -L - Force UTF8 (Unicode) flag on columns. - L - Implicit UUID columns. L - CRUD methods. =head2 Experimental -These components are under development, there interfaces may -change, they may not work, etc. So, use them if you want, but +These components are under development, their interfaces may +change, they may not work, etc. So, use them if you want, but be warned. -L - Hooks for Storable freeze/thaw. - -L - Hooks for Storable freeze/thaw. - L - Validate all data before submitting to your database. =head2 Core -These are the components that all, or nearly all, people will use -without even knowing it. These components provide most of +These are the components that all, or nearly all, people will use +without even knowing it. These components provide most of DBIx::Class' functionality. L - Loads various components that "most people" would want. +L - Lets you build groups of accessors. + L - Non-recommended classdata schema component. L - Automatically create objects from column data. -L - Inter-table relationships. - L - This class contains methods for handling primary keys and methods depending on them. -L - Basic row methods. +L - Inter-table relationships. L - Provides a classdata table object and method proxies. -L - Lets you build groups of accessors. - -=head1 CREATEING - -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 -classes 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. +L - Basic row methods. =head1 SEE ALSO L -L - =head1 AUTHOR Aran Clary Deltac -