.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "DBIx::Class::Manual::Component 3pm"
.TH DBIx::Class::Manual::Component 3pm "2022-05-21" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DBIx::Class::Manual::Component \- Developing DBIx::Class Components
.SH "WHAT IS A COMPONENT"
.IX Header "WHAT IS A COMPONENT"
A component is a module that can be added in to your DBIx::Class
classes to provide extra functionality. A good example is the PK::Auto
component which automatically retrieves primary keys that the database
itself creates, after the insert has happened.
.SH "USING"
.IX Header "USING"
Components are loaded using the \fBload_components()\fR method within your
DBIx::Class classes.
.PP
.Vb 3
\&  package My::Thing;
\&  use base qw( DBIx::Class::Core );
\&  _\|_PACKAGE_\|_\->load_components(qw/InflateColumn::DateTime TimeStamp/);
.Ve
.PP
Generally you do not want to specify the full package name
of a component, instead take off the DBIx::Class:: part of
it and just include the rest.  If you do want to load a
component outside of the normal namespace you can do so
by prepending the component name with a +.
.PP
.Vb 1
\&  _\|_PACKAGE_\|_\->load_components(qw/ +My::Component /);
.Ve
.PP
Once a component is loaded all of its methods, or otherwise,
that it provides will be available in your class.
.PP
The order in which is you load the components may be very
important, depending on the component. If you are not sure,
then read the docs for the components you are using and see
if they mention anything about the order in which you should
load them.
.SH "CREATING COMPONENTS"
.IX Header "CREATING COMPONENTS"
Making your own component is very easy.
.PP
.Vb 4
\&  package DBIx::Class::MyComp;
\&  use base qw(DBIx::Class);
\&  # Create methods, accessors, load other components, etc.
\&  1;
.Ve
.PP
When a component is loaded it is included in the calling
class' inheritance chain using Class::C3.  As well as
providing custom utility methods, a component may also
override methods provided by other core components, like
DBIx::Class::Row and others.  For example, you
could override the insert and delete methods.
.PP
.Vb 5
\&  sub insert {
\&    my $self = shift;
\&    # Do stuff with $self, like set default values.
\&    return $self\->next::method( @_ );
\&  }
\&
\&  sub delete {
\&    my $self = shift;
\&    # Do stuff with $self.
\&    return $self\->next::method( @_ );
\&  }
.Ve
.PP
Now, the order that a component is loaded is very important.  Components
that are loaded first are the first ones in the inheritance stack.  So, if
you override \fBinsert()\fR but the DBIx::Class::Row component is loaded first
then your \fBinsert()\fR will never be called, since the DBIx::Class::Row \fBinsert()\fR
will be called first.  If you are unsure as to why a given method is not
being called try printing out the current linearized \s-1MRO.\s0
.PP
.Vb 1
\&  print join \*(Aq, \*(Aq => mro::get_linear_isa(\*(AqYourClass::Name\*(Aq);
.Ve
.SH "EXISTING COMPONENTS"
.IX Header "EXISTING COMPONENTS"
.SS "Extra"
.IX Subsection "Extra"
These components provide extra functionality beyond
basic functionality that you can't live without.
.PP
DBIx::Class::CDBICompat \- Class::DBI Compatibility layer.
.PP
DBIx::Class::FormTools \- Build forms with multiple interconnected objects.
.PP
DBIx::Class::HTMLWidget \- Like FromForm but with DBIx::Class and HTML::Widget.
.PP
DBIx::Class::Ordered \- Modify the position of objects in an ordered list.
.PP
DBIx::Class::PK::Auto \- Retrieve automatically created primary keys upon insert.
.PP
DBIx::Class::QueriesTime \- Display the amount of time it takes to run queries.
.PP
DBIx::Class::RandomStringColumns \- Declare virtual columns that return random strings.
.PP
DBIx::Class::UUIDColumns \- Implicit \s-1UUID\s0 columns.
.PP
DBIx::Class::WebForm \- \s-1CRUD\s0 methods.
.SS "Experimental"
.IX Subsection "Experimental"
These components are under development, their interfaces may
change, they may not work, etc.  So, use them if you want, but
be warned.
.PP
DBIx::Class::Validation \- Validate all data before submitting to your database.
.SS "Core"
.IX Subsection "Core"
These are the components that all, or nearly all, people will use
without even knowing it.  These components provide most of
DBIx::Class' functionality.
.PP
DBIx::Class::Core \- Loads various components that \*(L"most people\*(R" would want.
.PP
DBIx::Class::AccessorGroup \- Lets you build groups of accessors.
.PP
DBIx::Class::DB \- Non-recommended classdata schema component.
.PP
DBIx::Class::InflateColumn \- Automatically create objects from column data.
.PP
DBIx::Class::PK \- This class contains methods for handling primary keys and methods depending on them.
.PP
DBIx::Class::Relationship \- Inter-table relationships.
.PP
DBIx::Class::ResultSourceProxy::Table \- Provides a classdata table object and method proxies.
.PP
DBIx::Class::Row \- Basic row methods.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
DBIx::Class::Manual::Cookbook
.SH "FURTHER QUESTIONS?"
.IX Header "FURTHER QUESTIONS?"
Check the list of additional \s-1DBIC\s0 resources.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This module is free software copyright
by the DBIx::Class (\s-1DBIC\s0) authors. You can
redistribute it and/or modify it under the same terms as the
DBIx::Class library.