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