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

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "Catalyst::View::Component::SubInclude 3"
 127 .TH Catalyst::View::Component::SubInclude 3 "2010-05-16" "perl v5.8.8" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 Catalyst::View::Component::SubInclude \- Use subincludes in your Catalyst views
 134 .SH "VERSION"
 135 .IX Header "VERSION"
 136 Version 0.08
 137 .SH "SYNOPSIS"
 138 .IX Header "SYNOPSIS"
 139 .Vb 2
 140 \&  package MyApp::View::TT;
 141 \&  use Moose;
 142 \&
 143 \&  extends \*(AqCatalyst::View::TT\*(Aq;
 144 \&  with \*(AqCatalyst::View::Component::SubInclude\*(Aq;
 145 \&
 146 \&  _\|_PACKAGE_\|_\->config( subinclude_plugin => \*(AqSubRequest\*(Aq );
 147 .Ve
 148 .PP
 149 Then, somewhere in your templates:
 150 .PP
 151 .Vb 2
 152 \&  [% subinclude(\*(Aq/my/widget\*(Aq) %]
 153 \&  [% subinclude_using(\*(AqSubRequest\*(Aq, \*(Aq/page/footer\*(Aq) %]
 154 .Ve
 155 .SH "DESCRIPTION"
 156 .IX Header "DESCRIPTION"
 157 \&\f(CW\*(C`Catalyst::View::Component::SubInclude\*(C'\fR allows you to include content in your
 158 templates (or, more generally, somewhere in your view's \f(CW\*(C`render\*(C'\fR processing)
 159 which comes from another action in your application. It's implemented as a
 160 Moose::Role, so using Moose in your view is required.
 161 .PP
 162 Simply put, it's a way to include the output of a Catalyst sub-request somewhere
 163 in your page.
 164 .PP
 165 It's built in an extensible way so that you're free to use sub-requests, Varnish
 166 \&\s-1ESI\s0 (<http://www.catalystframework.org/calendar/2008/17>) or any other
 167 sub-include plugin you might want to implement. An \s-1LWP\s0 plugin seems useful and
 168 might be developed in the future.
 169 .SH "STASH FUNCTIONS"
 170 .IX Header "STASH FUNCTIONS"
 171 This component does its magic by exporting a \f(CW\*(C`subinclude\*(C'\fR coderef entry to the
 172 stash. This way, it's easily accessible by the templates (which is the most
 173 common use-case).
 174 .ie n .SS """subinclude( $path, @args )"""
 175 .el .SS "\f(CWsubinclude( $path, @args )\fP"
 176 .IX Subsection "subinclude( $path, @args )"
 177 This will render and return the body of the included resource (as specified by
 178 \&\f(CW$path\fR) using the default subinclude plugin.
 179 .ie n .SS """subinclude_using( $plugin, $path, @args )"""
 180 .el .SS "\f(CWsubinclude_using( $plugin, $path, @args )\fP"
 181 .IX Subsection "subinclude_using( $plugin, $path, @args )"
 182 This will render and return the body of the included resource (as specified by
 183 \&\f(CW$path\fR) using the specified subinclude plugin.
 184 .PP
 185 The \f(CW\*(C`subinclude\*(C'\fR function above is implemented basically as a shortcut which
 186 calls this function using the default plugin as the first parameter.
 187 .SH "SUBINCLUDE PLUGINS"
 188 .IX Header "SUBINCLUDE PLUGINS"
 189 The module comes with two subinclude plugins:
 190 SubRequest,
 191 Visit and
 192 \&\s-1ESI\s0.
 193 .PP
 194 By default, the \f(CW\*(C`SubRequest\*(C'\fR plugin will be used. This can be changed in the
 195 view's configuration options (either in the config file or in the view module
 196 itself).
 197 .PP
 198 Configuration file example:
 199 .PP
 200 .Vb 3
 201 \&  <View::TT>
 202 \&      subinclude_plugin   ESI
 203 \&  </View::TT>
 204 .Ve
 205 .ie n .SS """set_subinclude_plugin( $plugin )"""
 206 .el .SS "\f(CWset_subinclude_plugin( $plugin )\fP"
 207 .IX Subsection "set_subinclude_plugin( $plugin )"
 208 This method changes the current active subinclude plugin in runtime. It expects
 209 the plugin suffix (e.g. \f(CW\*(C`ESI\*(C'\fR or \f(CW\*(C`SubRequest\*(C'\fR) or a fully-qualified class
 210 name in the \f(CW\*(C`Catalyst::View::Component::SubInclude\*(C'\fR namespace.
 211 .SS "Writing plugins"
 212 .IX Subsection "Writing plugins"
 213 If writing your own plugin, keep in kind plugins are required to implement a
 214 class method \f(CW\*(C`generate_subinclude\*(C'\fR with the following signature:
 215 .PP
 216 .Vb 3
 217 \&  sub generate_subinclude {
 218 \&      my ($class, $c, @args) = @_;
 219 \&  }
 220 .Ve
 221 .PP
 222 The default plugin is stored in the \f(CW\*(C`subinclude_plugin\*(C'\fR which can be changed
 223 in runtime. It expects a fully qualified class name.
 224 .SH "SEE ALSO"
 225 .IX Header "SEE ALSO"
 226 Catalyst::Plugin::SubRequest,
 227 Moose::Role, Moose,
 228 <http://www.catalystframework.org/calendar/2008/17>
 229 .SH "BUGS"
 230 .IX Header "BUGS"
 231 Please report any bugs or feature requests to
 232 \&\f(CW\*(C`bug\-catalyst\-view\-component\-subinclude at rt.cpan.org\*(C'\fR, or through the web interface at
 233 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Catalyst\-View\-Component\-SubInclude>.
 234 I will be notified, and then you'll automatically be notified of progress on
 235 your bug as I make changes.
 236 .SH "AUTHOR"
 237 .IX Header "AUTHOR"
 238 Nilson Santos Figueiredo Junior, \f(CW\*(C`<nilsonsfj at cpan.org>\*(C'\fR
 239 .SH "CONTRIBUTORS"
 240 .IX Header "CONTRIBUTORS"
 241 Tomas Doran (t0m) \f(CW\*(C`<bobtfish@bobtfish.net\*(C'\fR.
 242 .SH "SPONSORSHIP"
 243 .IX Header "SPONSORSHIP"
 244 Development sponsored by Ionzero \s-1LLC\s0 <http://www.ionzero.com/>.
 245 .SH "COPYRIGHT & LICENSE"
 246 .IX Header "COPYRIGHT & LICENSE"
 247 Copyright (C) 2010 Nilson Santos Figueiredo Junior and the above contributors.
 248 .PP
 249 Copyright (C) 2009 Nilson Santos Figueiredo Junior.
 250 .PP
 251 Copyright (C) 2009 Ionzero \s-1LLC\s0.
 252 .PP
 253 This program is free software; you can redistribute it and/or modify it
 254 under the same terms as Perl itself.