1
2=head1 NAME
3
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.
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::Core );
20  __PACKAGE__->load_components(qw/InflateColumn::DateTime TimeStamp/);
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
28  __PACKAGE__->load_components(qw/ +My::Component /);
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 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.
38
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
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
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  }
60  
61  sub delete {
62    my $self = shift;
63    # Do stuff with $self.
64    return $self->next::method( @_ );
65  }
66
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 
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
78=head1 EXISTING COMPONENTS
79
80=head2 Extra
81
82These components provide extra functionality beyond 
83basic functionality that you can't live without.
84
85L<DBIx::Class::Serialize::Storable> - Hooks for Storable freeze/thaw.
86
87L<DBIx::Class::CDBICompat> - Class::DBI Compatibility layer.
88
89L<DBIx::Class::FormTools> - Build forms with multiple interconnected objects.
90
91L<DBIx::Class::HTMLWidget> - Like FromForm but with DBIx::Class and HTML::Widget.
92
93L<DBIx::Class::Ordered> - Modify the position of objects in an ordered list.
94
95L<DBIx::Class::PK::Auto> - Retrieve automatically created primary keys upon insert.
96
97L<DBIx::Class::QueriesTime> - Display the amount of time it takes to run queries.
98
99L<DBIx::Class::RandomStringColumns> - Declare virtual columns that return random strings.
100
101L<DBIx::Class::UTF8Columns> - Force UTF8 (Unicode) flag on columns.
102
103L<DBIx::Class::UUIDColumns> - Implicit UUID columns.
104
105L<DBIx::Class::WebForm> - CRUD methods.
106
107=head2 Experimental
108
109These components are under development, their interfaces may
110change, they may not work, etc.  So, use them if you want, but
111be warned.
112
113L<DBIx::Class::Validation> - Validate all data before submitting to your database.
114
115=head2 Core
116
117These are the components that all, or nearly all, people will use
118without even knowing it.  These components provide most of
119DBIx::Class' functionality.
120
121L<DBIx::Class::Core> - Loads various components that "most people" would want.
122
123L<DBIx::Class::AccessorGroup> - Lets you build groups of accessors.
124
125L<DBIx::Class::DB> - Non-recommended classdata schema component.
126
127L<DBIx::Class::InflateColumn> - Automatically create objects from column data.
128
129L<DBIx::Class::PK> - This class contains methods for handling primary keys and methods depending on them.
130
131L<DBIx::Class::Relationship> - Inter-table relationships.
132
133L<DBIx::Class::ResultSourceProxy::Table> - Provides a classdata table object and method proxies.
134
135L<DBIx::Class::Row> - Basic row methods.
136
137=head1 SEE ALSO
138
139L<DBIx::Class::Manual::Cookbook>
140
141=head1 AUTHOR
142
143Aran Clary Deltac <bluefeet@cpan.org>
144