local-lib5/man/man3/Catalyst::Helper.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::Helper 3"
 132 .TH Catalyst::Helper 3 "2009-12-06" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Catalyst::Helper \- Bootstrap a Catalyst application
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&  catalyst.pl <myappname>
 139 .Ve
 140 .SH "DESCRIPTION"
 141 .IX Header "DESCRIPTION"
 142 This module is used by \fBcatalyst.pl\fR to create a set of scripts for a
 143 new catalyst application. The scripts each contain documentation and
 144 will output help on how to use them if called incorrectly or in some
 145 cases, with no arguments.
 146 .PP
 147 It also provides some useful methods for a Helper module to call when
 148 creating a component. See \*(L"\s-1METHODS\s0\*(R".
 149 .SH "SCRIPTS"
 150 .IX Header "SCRIPTS"
 151 .Sh "_create.pl"
 152 .IX Subsection "_create.pl"
 153 Used to create new components for a catalyst application at the
 154 development stage.
 155 .Sh "_server.pl"
 156 .IX Subsection "_server.pl"
 157 The catalyst test server, starts an \s-1HTTPD\s0 which outputs debugging to
 158 the terminal.
 159 .Sh "_test.pl"
 160 .IX Subsection "_test.pl"
 161 A script for running tests from the command\-line.
 162 .Sh "_cgi.pl"
 163 .IX Subsection "_cgi.pl"
 164 Run your application as a \s-1CGI\s0.
 165 .Sh "_fastcgi.pl"
 166 .IX Subsection "_fastcgi.pl"
 167 Run the application as a fastcgi app. Either by hand, or call this
 168 from FastCgiServer in your http server config.
 169 .SH "HELPERS"
 170 .IX Header "HELPERS"
 171 The \*(L"_create.pl\*(R" script creates application components using Helper
 172 modules. The Catalyst team provides a good number of Helper modules
 173 for you to use. You can also add your own.
 174 .PP
 175 Helpers are classes that provide two methods.
 176 .PP
 177 .Vb 2
 178 \&    * mk_compclass \- creates the Component class
 179 \&    * mk_comptest  \- creates the Component test
 180 .Ve
 181 .PP
 182 So when you call \f(CW\*(C`scripts/myapp_create.pl view MyView TT\*(C'\fR, create
 183 will try to execute Catalyst::Helper::View::TT\->mk_compclass and
 184 Catalyst::Helper::View::TT\->mk_comptest.
 185 .PP
 186 See Catalyst::Helper::View::TT and
 187 Catalyst::Helper::Model::DBIC::Schema for examples.
 188 .PP
 189 All helper classes should be under one of the following namespaces.
 190 .PP
 191 .Vb 3
 192 \&    Catalyst::Helper::Model::
 193 \&    Catalyst::Helper::View::
 194 \&    Catalyst::Helper::Controller::
 195 .Ve
 196 .Sh "\s-1COMMON\s0 \s-1HELPERS\s0"
 197 .IX Subsection "COMMON HELPERS"
 198 .IP "\(bu" 4
 199 Catalyst::Helper::Model::DBIC::Schema \- DBIx::Class models
 200 .IP "\(bu" 4
 201 Catalyst::Helper::View::TT \- Template Toolkit view
 202 .IP "\(bu" 4
 203 Catalyst::Helper::Model::LDAP
 204 .IP "\(bu" 4
 205 Catalyst::Helper::Model::Adaptor \- wrap any class into a Catalyst model
 206 .PP
 207 \fI\s-1NOTE\s0\fR
 208 .IX Subsection "NOTE"
 209 .PP
 210 The helpers will read author name from /etc/passwd by default.
 211 To override, please export the \s-1AUTHOR\s0 variable.
 212 .SH "METHODS"
 213 .IX Header "METHODS"
 214 .Sh "mk_compclass"
 215 .IX Subsection "mk_compclass"
 216 This method in your Helper module is called with \f(CW$helper\fR
 217 which is a Catalyst::Helper object, and whichever other arguments
 218 the user added to the command\-line. You can use the \f(CW$helper\fR to call methods
 219 described below.
 220 .PP
 221 If the Helper module does not contain a \f(CW\*(C`mk_compclass\*(C'\fR method, it
 222 will fall back to calling \*(L"render_file\*(R", with an argument of
 223 \&\f(CW\*(C`compclass\*(C'\fR.
 224 .Sh "mk_comptest"
 225 .IX Subsection "mk_comptest"
 226 This method in your Helper module is called with \f(CW$helper\fR
 227 which is a Catalyst::Helper object, and whichever other arguments
 228 the user added to the command\-line. You can use the \f(CW$helper\fR to call methods
 229 described below.
 230 .PP
 231 If the Helper module does not contain a \f(CW\*(C`mk_compclass\*(C'\fR method, it
 232 will fall back to calling \*(L"render_file\*(R", with an argument of
 233 \&\f(CW\*(C`comptest\*(C'\fR.
 234 .Sh "mk_stuff"
 235 .IX Subsection "mk_stuff"
 236 This method is called if the user does not supply any of the usual
 237 component types \f(CW\*(C`view\*(C'\fR, \f(CW\*(C`controller\*(C'\fR, \f(CW\*(C`model\*(C'\fR. It is passed the
 238 \&\f(CW$helper\fR object (an instance of Catalyst::Helper), and any other
 239 arguments the user typed.
 240 .PP
 241 There is no fallback for this method.
 242 .SH "INTERNAL METHODS"
 243 .IX Header "INTERNAL METHODS"
 244 These are the methods that the Helper classes can call on the
 245 <$helper> object passed to them.
 246 .ie n .Sh "render_file ($file, $path\fP, \f(CW$vars)"
 247 .el .Sh "render_file ($file, \f(CW$path\fP, \f(CW$vars\fP)"
 248 .IX Subsection "render_file ($file, $path, $vars)"
 249 Render and create a file from a template in \s-1DATA\s0 using Template
 250 Toolkit. \f(CW$file\fR is the relevent chunk of the _\|_DATA_\|_ section, \f(CW$path\fR is
 251 the path to the file and \f(CW$vars\fR is the hashref as expected by
 252 Template Toolkit.
 253 .ie n .Sh "get_file ($class, $file)"
 254 .el .Sh "get_file ($class, \f(CW$file\fP)"
 255 .IX Subsection "get_file ($class, $file)"
 256 Fetch file contents from the \s-1DATA\s0 section. This is used internally by
 257 \&\*(L"render_file\*(R".  \f(CW$class\fR is the name of the class to get the \s-1DATA\s0
 258 section from.  _\|_PACKAGE_\|_ or ( \fIcaller\fR\|(0) )[0] might be sensible
 259 values for this.
 260 .Sh "mk_app"
 261 .IX Subsection "mk_app"
 262 Create the main application skeleton. This is called by catalyst.pl.
 263 .Sh "mk_component ($app)"
 264 .IX Subsection "mk_component ($app)"
 265 This method is called by create.pl to make new components
 266 for your application.
 267 .Sh "mk_dir ($path)"
 268 .IX Subsection "mk_dir ($path)"
 269 Surprisingly, this function makes a directory.
 270 .ie n .Sh "mk_file ($file, $content)"
 271 .el .Sh "mk_file ($file, \f(CW$content\fP)"
 272 .IX Subsection "mk_file ($file, $content)"
 273 Writes content to a file. Called by \*(L"render_file\*(R".
 274 .Sh "next_test ($test_name)"
 275 .IX Subsection "next_test ($test_name)"
 276 Calculates the name of the next numbered test file and returns it.
 277 Don't give the number or the .t suffix for the test name.
 278 .Sh "get_sharedir_file"
 279 .IX Subsection "get_sharedir_file"
 280 Method for getting a file out of share/
 281 .Sh "render_file_contents"
 282 .IX Subsection "render_file_contents"
 283 Process a Template::Toolkit template.
 284 .Sh "render_sharedir_file"
 285 .IX Subsection "render_sharedir_file"
 286 Render a template/image file from our share directory
 287 .SH "NOTE"
 288 .IX Header "NOTE"
 289 The helpers will read author name from /etc/passwd by default.
 290 To override, please export the \s-1AUTHOR\s0 variable.
 291 .SH "SEE ALSO"
 292 .IX Header "SEE ALSO"
 293 Catalyst::Manual, Catalyst::Test, Catalyst::Request,
 294 Catalyst::Response, Catalyst
 295 .SH "AUTHORS"
 296 .IX Header "AUTHORS"
 297 Catalyst Contributors, see Catalyst.pm
 298 .SH "LICENSE"
 299 .IX Header "LICENSE"
 300 This library is free software. You can redistribute it and/or modify
 301 it under the same terms as Perl itself.