Clarify licensing, ensure footers are consistent throughout the project
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class / Manual / Component.pod
1
2 =head1 NAME
3
4 DBIx::Class::Manual::Component - Developing DBIx::Class Components
5
6 =head1 WHAT IS A COMPONENT
7
8 A component is a module that can be added in to your DBIx::Class
9 classes to provide extra functionality. A good example is the PK::Auto
10 component which automatically retrieves primary keys that the database
11 itself creates, after the insert has happened.
12
13 =head1 USING
14
15 Components are loaded using the load_components() method within your
16 DBIx::Class classes.
17
18   package My::Thing;
19   use base qw( DBIx::Class::Core );
20   __PACKAGE__->load_components(qw/InflateColumn::DateTime TimeStamp/);
21
22 Generally you do not want to specify the full package name
23 of a component, instead take off the DBIx::Class:: part of
24 it and just include the rest.  If you do want to load a
25 component outside of the normal namespace you can do so
26 by prepending the component name with a +.
27
28   __PACKAGE__->load_components(qw/ +My::Component /);
29
30 Once a component is loaded all of its methods, or otherwise,
31 that it provides will be available in your class.
32
33 The order in which is you load the components may be very
34 important, depending on the component. If you are not sure,
35 then read the docs for the components you are using and see
36 if they mention anything about the order in which you should
37 load them.
38
39 =head1 CREATING COMPONENTS
40
41 Making 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
48 When a component is loaded it is included in the calling
49 class' inheritance chain using L<Class::C3>.  As well as
50 providing custom utility methods, a component may also
51 override methods provided by other core components, like
52 L<DBIx::Class::Row> and others.  For example, you
53 could 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
67 Now, the order that a component is loaded is very important.  Components
68 that are loaded first are the first ones in the inheritance stack.  So, if
69 you override insert() but the DBIx::Class::Row component is loaded first
70 then your insert() will never be called, since the DBIx::Class::Row insert()
71 will be called first.  If you are unsure as to why a given method is not
72 being called try printing out the current linearized MRO.
73
74   print join ', ' => mro::get_linear_isa('YourClass::Name');
75
76 =head1 EXISTING COMPONENTS
77
78 =head2 Extra
79
80 These components provide extra functionality beyond
81 basic functionality that you can't live without.
82
83 L<DBIx::Class::CDBICompat> - Class::DBI Compatibility layer.
84
85 L<DBIx::Class::FormTools> - Build forms with multiple interconnected objects.
86
87 L<DBIx::Class::HTMLWidget> - Like FromForm but with DBIx::Class and HTML::Widget.
88
89 L<DBIx::Class::Ordered> - Modify the position of objects in an ordered list.
90
91 L<DBIx::Class::PK::Auto> - Retrieve automatically created primary keys upon insert.
92
93 L<DBIx::Class::QueriesTime> - Display the amount of time it takes to run queries.
94
95 L<DBIx::Class::RandomStringColumns> - Declare virtual columns that return random strings.
96
97 L<DBIx::Class::UUIDColumns> - Implicit UUID columns.
98
99 L<DBIx::Class::WebForm> - CRUD methods.
100
101 =head2 Experimental
102
103 These components are under development, their interfaces may
104 change, they may not work, etc.  So, use them if you want, but
105 be warned.
106
107 L<DBIx::Class::Validation> - Validate all data before submitting to your database.
108
109 =head2 Core
110
111 These are the components that all, or nearly all, people will use
112 without even knowing it.  These components provide most of
113 DBIx::Class' functionality.
114
115 L<DBIx::Class::Core> - Loads various components that "most people" would want.
116
117 L<DBIx::Class::AccessorGroup> - Lets you build groups of accessors.
118
119 L<DBIx::Class::DB> - Non-recommended classdata schema component.
120
121 L<DBIx::Class::InflateColumn> - Automatically create objects from column data.
122
123 L<DBIx::Class::PK> - This class contains methods for handling primary keys and methods depending on them.
124
125 L<DBIx::Class::Relationship> - Inter-table relationships.
126
127 L<DBIx::Class::ResultSourceProxy::Table> - Provides a classdata table object and method proxies.
128
129 L<DBIx::Class::Row> - Basic row methods.
130
131 =head1 SEE ALSO
132
133 L<DBIx::Class::Manual::Cookbook>
134
135 =head1 FURTHER QUESTIONS?
136
137 Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
138
139 =head1 COPYRIGHT AND LICENSE
140
141 This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
142 by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
143 redistribute it and/or modify it under the same terms as the
144 L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.