Merge 'trunk' into 'ado_mssql'
[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / Manual / Component.pod
CommitLineData
3d18a9c1 1
2=head1 NAME
3
4a3c6354 4DBIx::Class::Manual::Component - Developing DBIx::Class Components
5
6=head1 WHAT IS A COMPONENT
7
8A component is a module that can be added in to your DBIx::Class
9classes to provide extra functionality. A good example is the PK::Auto
10component which automatically retrieves primary keys that the database
11itself creates, after the insert has happened.
3d18a9c1 12
13=head1 USING
14
15Components are loaded using the load_components() method within your
16DBIx::Class classes.
17
18 package My::Thing;
19 use base qw( DBIx::Class );
4a3c6354 20 __PACKAGE__->load_components(qw/ PK::Auto Core /);
3d18a9c1 21
22Generally you do not want to specify the full package name
23of a component, instead take off the DBIx::Class:: part of
24it and just include the rest. If you do want to load a
25component outside of the normal namespace you can do so
26by prepending the component name with a +.
27
4a3c6354 28 __PACKAGE__->load_components(qw/ +My::Component /);
3d18a9c1 29
30Once a component is loaded all of it's methods, or otherwise,
31that it provides will be available in your class.
32
33The order in which is you load the components may be
d444f9fa 34very important, depending on the component. The general
3d18a9c1 35rule of thumb is to first load extra components and then
36load core ones last. If you are not sure, then read the
37docs for the components you are using and see if they
38mention anything about the order in which you should load
39them.
40
4a3c6354 41=head1 CREATING COMPONENTS
42
43Making your own component is very easy.
44
45 package DBIx::Class::MyComp;
46 use base qw(DBIx::Class);
47 # Create methods, accessors, load other components, etc.
48 1;
49
50When a component is loaded it is included in the calling
51class' inheritance chain using L<Class::C3>. As well as
52providing custom utility methods, a component may also
53override methods provided by other core components, like
54L<DBIx::Class::Row> and others. For example, you
55could override the insert and delete methods.
56
57 sub insert {
58 my $self = shift;
59 # Do stuff with $self, like set default values.
60 return $self->next::method( @_ );
61 }
62
63 sub delete {
64 my $self = shift;
65 # Do stuff with $self.
66 return $self->next::method( @_ );
67 }
68
69Now, the order that a component is loaded is very important. Components
70that are loaded first are the first ones in the inheritance stack. So, if
71you override insert() but the DBIx::Class::Row component is loaded first
72then your insert() will never be called, since the DBIx::Class::Row insert()
73will be called first. If you are unsure as to why a given method is not
74being called try printing out the Class::C3 inheritance stack.
75
76 print join ', ' => Class::C3::calculateMRO('YourClass::Name');
77
78Check out the L<Class::C3> docs for more information about inheritance.
79
d444f9fa 80=head1 EXISTING COMPONENTS
3d18a9c1 81
82=head2 Extra
83
d444f9fa 84These components provide extra functionality beyond
85basic functionality that you can't live without.
3d18a9c1 86
e1bc5196 87L<DBIx::Class::Serialize::Storable> - Hooks for Storable freeze/thaw.
88
880a1a0c 89L<DBIx::Class::CDBICompat> - Class::DBI Compatibility layer.
3d18a9c1 90
3d18a9c1 91L<DBIx::Class::FormTools> - Build forms with multiple interconnected objects.
92
93L<DBIx::Class::HTMLWidget> - Like FromForm but with DBIx::Class and HTML::Widget.
94
1caff56e 95L<DBIx::Class::Ordered> - Modify the position of objects in an ordered list.
d444f9fa 96
1caff56e 97L<DBIx::Class::PK::Auto> - Retrieve automatically created primary keys upon insert.
10ab0322 98
3d18a9c1 99L<DBIx::Class::QueriesTime> - Display the amount of time it takes to run queries.
100
101L<DBIx::Class::RandomStringColumns> - Declare virtual columns that return random strings.
102
103L<DBIx::Class::UTF8Columns> - Force UTF8 (Unicode) flag on columns.
104
105L<DBIx::Class::UUIDColumns> - Implicit UUID columns.
106
107L<DBIx::Class::WebForm> - CRUD methods.
108
109=head2 Experimental
110
111These components are under development, there interfaces may
112change, they may not work, etc. So, use them if you want, but
113be warned.
114
3d18a9c1 115L<DBIx::Class::Validation> - Validate all data before submitting to your database.
116
117=head2 Core
118
119These are the components that all, or nearly all, people will use
120without even knowing it. These components provide most of
121DBIx::Class' functionality.
122
d444f9fa 123L<DBIx::Class::AccessorGroup> - Lets you build groups of accessors.
124
3d18a9c1 125L<DBIx::Class::Core> - Loads various components that "most people" would want.
126
127L<DBIx::Class::DB> - Non-recommended classdata schema component.
128
129L<DBIx::Class::InflateColumn> - Automatically create objects from column data.
130
3d18a9c1 131L<DBIx::Class::PK> - This class contains methods for handling primary keys and methods depending on them.
132
d444f9fa 133L<DBIx::Class::Relationship> - Inter-table relationships.
3d18a9c1 134
135L<DBIx::Class::ResultSourceProxy::Table> - Provides a classdata table object and method proxies.
136
d444f9fa 137L<DBIx::Class::Row> - Basic row methods.
3d18a9c1 138
3d18a9c1 139=head1 SEE ALSO
140
141L<DBIx::Class::Manual::Cookbook>
142
3d18a9c1 143=head1 AUTHOR
144
145Aran Clary Deltac <bluefeet@cpan.org>