local-lib5/man/man3/Catalyst::Component.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Catalyst::Component 3"
 132 .TH Catalyst::Component 3 "2009-09-02" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Catalyst::Component \- Catalyst Component Base Class
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 2
 138 \&    # lib/MyApp/Model/Something.pm
 139 \&    package MyApp::Model::Something;
 140 .Ve
 141 .PP
 142 .Vb 1
 143 \&    use base 'Catalyst::Component';
 144 .Ve
 145 .PP
 146 .Vb 1
 147 \&    __PACKAGE__\->config( foo => 'bar' );
 148 .Ve
 149 .PP
 150 .Vb 4
 151 \&    sub test {
 152 \&        my $self = shift;
 153 \&        return $self\->{foo};
 154 \&    }
 155 .Ve
 156 .PP
 157 .Vb 4
 158 \&    sub forward_to_me {
 159 \&        my ( $self, $c ) = @_;
 160 \&        $c\->response\->output( $self\->{foo} );
 161 \&    }
 162 .Ve
 163 .PP
 164 .Vb 1
 165 \&    1;
 166 .Ve
 167 .PP
 168 .Vb 2
 169 \&    # Methods can be a request step
 170 \&    $c\->forward(qw/MyApp::Model::Something forward_to_me/);
 171 .Ve
 172 .PP
 173 .Vb 2
 174 \&    # Or just methods
 175 \&    print $c\->comp('MyApp::Model::Something')\->test;
 176 .Ve
 177 .PP
 178 .Vb 1
 179 \&    print $c\->comp('MyApp::Model::Something')\->{foo};
 180 .Ve
 181 .SH "DESCRIPTION"
 182 .IX Header "DESCRIPTION"
 183 This is the universal base class for Catalyst components
 184 (Model/View/Controller).
 185 .PP
 186 It provides you with a generic \fInew()\fR for instantiation through Catalyst's
 187 component loader with \fIconfig()\fR support and a \fIprocess()\fR method placeholder.
 188 .SH "METHODS"
 189 .IX Header "METHODS"
 190 .ie n .Sh "new($c, $arguments)"
 191 .el .Sh "new($c, \f(CW$arguments\fP)"
 192 .IX Subsection "new($c, $arguments)"
 193 Called by \s-1COMPONENT\s0 to instantiate the component; should return an object
 194 to be stored in the application's component hash.
 195 .Sh "\s-1COMPONENT\s0"
 196 .IX Subsection "COMPONENT"
 197 \&\f(CW\*(C`my $component_instance = $component\->COMPONENT($app, $arguments);\*(C'\fR
 198 .PP
 199 If this method is present (as it is on all Catalyst::Component subclasses,
 200 it is called by Catalyst during setup_components with the application class
 201 as \f(CW$c\fR and any config entry on the application for this component (for example,
 202 in the case of MyApp::Controller::Foo this would be
 203 \&\f(CW\*(C`MyApp\->config('Controller::Foo' => \e%conf\*(C'\fR).
 204 The arguments are expected to be a hashref and are merged with the
 205 \&\f(CW\*(C`_\|_PACKAGE_\|_\->config\*(C'\fR hashref before calling \f(CW\*(C`\->new\*(C'\fR
 206 to instantiate the component.
 207 .PP
 208 You can override it in your components to do custom instantiation, using
 209 something like this:
 210 .PP
 211 .Vb 5
 212 \&  sub COMPONENT {
 213 \&      my ($class, $app, $args) = @_;
 214 \&      $args = $self\->merge_config_hashes($self\->config, $args);
 215 \&      return $class\->new($app, $args);
 216 \&  }
 217 .Ve
 218 .Sh "$c\->config"
 219 .IX Subsection "$c->config"
 220 .Sh "$c\->config($hashref)"
 221 .IX Subsection "$c->config($hashref)"
 222 .ie n .Sh "$c\->config($key, $value, ...)"
 223 .el .Sh "$c\->config($key, \f(CW$value\fP, ...)"
 224 .IX Subsection "$c->config($key, $value, ...)"
 225 Accessor for this component's config hash. Config values can be set as
 226 key value pair, or you can specify a hashref. In either case the keys
 227 will be merged with any existing config settings. Each component in
 228 a Catalyst application has its own config hash.
 229 .Sh "$c\->\fIprocess()\fP"
 230 .IX Subsection "$c->process()"
 231 This is the default method called on a Catalyst component in the dispatcher.
 232 For instance, Views implement this action to render the response body
 233 when you forward to them. The default is an abstract method.
 234 .ie n .Sh "$c\->merge_config_hashes( $hashref\fP, \f(CW$hashref )"
 235 .el .Sh "$c\->merge_config_hashes( \f(CW$hashref\fP, \f(CW$hashref\fP )"
 236 .IX Subsection "$c->merge_config_hashes( $hashref, $hashref )"
 237 Merges two hashes together recursively, giving right-hand precedence.
 238 Alias for the method in Catalyst::Utils.
 239 .SH "OPTIONAL METHODS"
 240 .IX Header "OPTIONAL METHODS"
 241 .ie n .Sh "\s-1ACCEPT_CONTEXT\s0($c, @args)"
 242 .el .Sh "\s-1ACCEPT_CONTEXT\s0($c, \f(CW@args\fP)"
 243 .IX Subsection "ACCEPT_CONTEXT($c, @args)"
 244 Catalyst components are normally initialized during server startup, either
 245 as a Class or a Instance. However, some components require information about
 246 the current request. To do so, they can implement an \s-1ACCEPT_CONTEXT\s0 method.
 247 .PP
 248 If this method is present, it is called during \f(CW$c\fR\->comp/controller/model/view
 249 with the current \f(CW$c\fR and any additional args (e.g. \f(CW$c\fR\->model('Foo', qw/bar baz/)
 250 would cause your MyApp::Model::Foo instance's \s-1ACCEPT_CONTEXT\s0 to be called with
 251 ($c, 'bar', 'baz')) and the return value of this method is returned to the
 252 calling code in the application rather than the component itself.
 253 .SH "SEE ALSO"
 254 .IX Header "SEE ALSO"
 255 Catalyst, Catalyst::Model, Catalyst::View, Catalyst::Controller.
 256 .SH "AUTHORS"
 257 .IX Header "AUTHORS"
 258 Catalyst Contributors, see Catalyst.pm
 259 .SH "COPYRIGHT"
 260 .IX Header "COPYRIGHT"
 261 This library is free software. You can redistribute it and/or modify it under
 262 the same terms as Perl itself.