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