Extra FAQ entry
[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 );
20   __PACKAGE__->load_components(qw/ PK::Auto Core /);
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 it's 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 
34 very important, depending on the component.  The general 
35 rule of thumb is to first load extra components and then 
36 load core ones last.  If you are not sure, then read the 
37 docs for the components you are using and see if they 
38 mention anything about the order in which you should load 
39 them.
40
41 =head1 CREATING COMPONENTS
42
43 Making 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
50 When a component is loaded it is included in the calling 
51 class' inheritance chain using L<Class::C3>.  As well as 
52 providing custom utility methods, a component may also 
53 override methods provided by other core components, like 
54 L<DBIx::Class::Row> and others.  For example, you 
55 could 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
69 Now, the order that a component is loaded is very important.  Components 
70 that are loaded first are the first ones in the inheritance stack.  So, if 
71 you override insert() but the DBIx::Class::Row component is loaded first 
72 then your insert() will never be called, since the DBIx::Class::Row insert() 
73 will be called first.  If you are unsure as to why a given method is not 
74 being called try printing out the Class::C3 inheritance stack.
75
76   print join ', ' => Class::C3::calculateMRO('YourClass::Name');
77
78 Check out the L<Class::C3> docs for more information about inheritance.
79
80 =head1 EXISTING COMPONENTS
81
82 =head2 Extra
83
84 These components provide extra functionality beyond 
85 basic functionality that you can't live without.
86
87 L<DBIx::Class::Serialize::Storable> - Hooks for Storable freeze/thaw.
88
89 L<DBIx::Class::CDBICompat> - Class::DBI Compatibility layer.
90
91 L<DBIx::Class::FormTools> - Build forms with multiple interconnected objects.
92
93 L<DBIx::Class::HTMLWidget> - Like FromForm but with DBIx::Class and HTML::Widget.
94
95 L<DBIx::Class::Ordered> - Modify the position of objects in an ordered list.
96
97 L<DBIx::Class::PK::Auto> - Retrieve automatically created primary keys upon insert.
98
99 L<DBIx::Class::QueriesTime> - Display the amount of time it takes to run queries.
100
101 L<DBIx::Class::RandomStringColumns> - Declare virtual columns that return random strings.
102
103 L<DBIx::Class::UTF8Columns> - Force UTF8 (Unicode) flag on columns.
104
105 L<DBIx::Class::UUIDColumns> - Implicit UUID columns.
106
107 L<DBIx::Class::WebForm> - CRUD methods.
108
109 =head2 Experimental
110
111 These components are under development, there interfaces may 
112 change, they may not work, etc.  So, use them if you want, but 
113 be warned.
114
115 L<DBIx::Class::Validation> - Validate all data before submitting to your database.
116
117 =head2 Core
118
119 These are the components that all, or nearly all, people will use 
120 without even knowing it.  These components provide most of 
121 DBIx::Class' functionality.
122
123 L<DBIx::Class::AccessorGroup> - Lets you build groups of accessors.
124
125 L<DBIx::Class::Core> - Loads various components that "most people" would want.
126
127 L<DBIx::Class::DB> - Non-recommended classdata schema component.
128
129 L<DBIx::Class::InflateColumn> - Automatically create objects from column data.
130
131 L<DBIx::Class::PK> - This class contains methods for handling primary keys and methods depending on them.
132
133 L<DBIx::Class::Relationship> - Inter-table relationships.
134
135 L<DBIx::Class::ResultSourceProxy::Table> - Provides a classdata table object and method proxies.
136
137 L<DBIx::Class::Row> - Basic row methods.
138
139 =head1 SEE ALSO
140
141 L<DBIx::Class::Manual::Cookbook>
142
143 =head1 AUTHOR
144
145 Aran Clary Deltac <bluefeet@cpan.org>