.\" 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 "Class::DBI::Relationship 3pm"
.TH Class::DBI::Relationship 3pm "2022-03-28" "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"
Class::DBI::Relationship \- base class for Relationships
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A Class::DBI class represents a database table. But merely being able
to represent single tables isn't really that useful \- databases are all
about relationships.
.PP
So, Class::DBI provides a variety of Relationship models to represent
common database occurences (HasA, HasMany and MightHave), and provides
a way to add others.
.SH "SUBCLASSING"
.IX Header "SUBCLASSING"
Relationships should inherit from Class::DBI::Relationship, and
provide a variety of methods to represent the relationship. For
examples of how these are used see Class::DBI::Relationship::HasA,
Class::DBI::Relationship::HasMany and Class::DBI::Relationship::MightHave.
.SS "remap_arguments"
.IX Subsection "remap_arguments"
.Vb 5
\&        sub remap_arguments { 
\&                my $self = shift;
\&                # process @_;
\&                return ($class, accessor, $foreign_class, $args)
\&        }
.Ve
.PP
Subclasses should define a 'remap_arguments' method that takes the
arguments with which your relationship method will be called, and
transforms them into the structure that the Relationship modules requires.
If this method is not provided, then it is assumed that your method will
be called with these 3 arguments in this order.
.PP
This should return a list of 4 items:
.IP "class" 4
.IX Item "class"
The Class::DBI subclass to which this relationship applies. This will be
passed in to you from the caller who actually set up the relationship,
and is available for you to call methods on whilst performing this
mapping. You should almost never need to change this.
.Sp
This usually an entire application base class (or Class::DBI itself),
but could be a single class wishing to override a default relationship.
.IP "accessor" 4
.IX Item "accessor"
The method in the class which will provide access to the results of
the relationship.
.IP "foreign_class" 4
.IX Item "foreign_class"
The class for the table with which the class has a relationship.
.IP "args" 4
.IX Item "args"
Any additional args that your relationship requires.  It is recommended
that you use this as a hashref to store any extra information your
relationship needs rather than adding extra accessors, as this information
will all be stored in the 'meta_info'.
.SS "triggers"
.IX Subsection "triggers"
.Vb 6
\&        sub triggers { 
\&                return (
\&                        before_create => sub { ... },
\&                        after_create  => sub { ... },
\&                );
\&        }
.Ve
.PP
Subclasses may define a 'triggers' method that returns a list of
triggers that the relationship needs. This method can be omitted if
there are no triggers to be set up.
.SS "methods"
.IX Subsection "methods"
.Vb 6
\&        sub methods { 
\&                return (
\&                        method1 => sub { ... },
\&                        method2 => sub { ... },
\&                );
\&        }
.Ve
.PP
Subclasses may define a 'methods' method that returns a list of methods
to facilitate the relationship that should be created in the calling
Class::DBI class.  This method can be omitted if there are no methods
to be set up.