From: Aran Deltac Date: Thu, 23 Mar 2006 21:48:43 +0000 (+0000) Subject: Component manual. X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=3d18a9c1993fb77df13803ad30978c590fb872e4;p=dbsrgits%2FDBIx-Class-Historic.git Component manual. --- diff --git a/lib/DBIx/Class/Manual/Component.pod b/lib/DBIx/Class/Manual/Component.pod new file mode 100644 index 0000000..1dfe90d --- /dev/null +++ b/lib/DBIx/Class/Manual/Component.pod @@ -0,0 +1,142 @@ + +=head1 NAME + +DBIx::Class::Manula::Component - Existing components and how to develop new ones. + +=head1 USING + +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 )); + +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 )); + +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. + +=head1 EXISTING + +=head2 Extra + +These components provide extra functionality above +and beyond what any normal user would need out of the +box. + +L - Class::DBI Compatability layer. + +L - Retrieve automatically created primary keys upon insert. + +L - Build forms with multiple interconnected objects. + +L - Like FromForm but with DBIx::Class and HTML::Widget. + +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 +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 +DBIx::Class' functionality. + +L - Loads various components that "most people" would want. + +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 - 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. + +=head1 SEE ALSO + +L + +L + +=head1 AUTHOR + +Aran Clary Deltac +