Commit | Line | Data |
3d18a9c1 |
1 | |
2 | =head1 NAME |
3 | |
d444f9fa |
4 | DBIx::Class::Manual::Component - Existing components and how to develop new ones. |
3d18a9c1 |
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 |
d444f9fa |
27 | very important, depending on the component. The general |
3d18a9c1 |
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 | |
d444f9fa |
34 | =head1 EXISTING COMPONENTS |
3d18a9c1 |
35 | |
36 | =head2 Extra |
37 | |
d444f9fa |
38 | These components provide extra functionality beyond |
39 | basic functionality that you can't live without. |
3d18a9c1 |
40 | |
880a1a0c |
41 | L<DBIx::Class::CDBICompat> - Class::DBI Compatibility layer. |
3d18a9c1 |
42 | |
3d18a9c1 |
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 | |
d444f9fa |
47 | L<DBIx::Class::PK::Auto> - Retrieve automatically created primary keys upon insert. |
48 | |
10ab0322 |
49 | L<DBIx::Class::Positional> - Modify the position of objects in an ordered list. |
50 | |
3d18a9c1 |
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 | |
1e3ff014 |
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 | |
10ab0322 |
77 | L<DBIx::Class::TokenGroup> - Search for tokens in a tree of groups. |
78 | |
3d18a9c1 |
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 | |
d444f9fa |
85 | L<DBIx::Class::AccessorGroup> - Lets you build groups of accessors. |
86 | |
3d18a9c1 |
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 | |
3d18a9c1 |
93 | L<DBIx::Class::PK> - This class contains methods for handling primary keys and methods depending on them. |
94 | |
d444f9fa |
95 | L<DBIx::Class::Relationship> - Inter-table relationships. |
3d18a9c1 |
96 | |
97 | L<DBIx::Class::ResultSourceProxy::Table> - Provides a classdata table object and method proxies. |
98 | |
d444f9fa |
99 | L<DBIx::Class::Row> - Basic row methods. |
3d18a9c1 |
100 | |
d444f9fa |
101 | =head1 CREATEING COMPONENTS |
3d18a9c1 |
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 |
d444f9fa |
111 | class' inheritance chain using L<Class::C3>. As well as |
3d18a9c1 |
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 | |
880a1a0c |
138 | Check out the L<Class::C3> docs for more information about inheritance. |
3d18a9c1 |
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 | |