.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" 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 .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "CGI::Application::Plugin::ErrorPage 3pm" .TH CGI::Application::Plugin::ErrorPage 3pm "2018-03-19" "perl v5.26.1" "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" CGI::Application::Plugin::ErrorPage \- A simple error page plugin for CGI::Application .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use CGI::Application::Plugin::ErrorPage \*(Aqerror\*(Aq; \& \& sub my_run_mode { \& my $self = shift; \& \& eval { .... }; \& \& if ($@) { \& # Send the gory details to the log for the developers \& warn "$@"; \& \& # Send a comprehensible message to the users \& return $self\->error( \& title => "Technical Failure\*(Aq, \& msg => "There was a techical failure during the operation.", \& ); \& } \& \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This plugin provides a shortcut for the common need of returning a simple error message to the user. .PP You are encouraged to provide a template file so that the error messages can be presented with a design consistent with the rest of your application. .PP A simple design is provided below to get to you started. .SS "A better default error page." .IX Subsection "A better default error page." If you don't install an \s-1AUTOLOAD\s0 run mode in the normal way in \f(CW\*(C`setup\*(C'\fR, this plugin will automatically install a reasonable default at the \f(CW\*(C`prerun\*(C'\fR stage, which returns an error page like this: .PP .Vb 4 \& return $c\->error( \& title => \*(AqThe requested page was not found.\*(Aq, \& msg => "(The page tried was: ".$c\->get_current_runmode.")" \& ); .Ve .SS "Relation to \fIerror_mode()\fP" .IX Subsection "Relation to error_mode()" CGI::Application includes \f(CW\*(C`error_mode()\*(C'\fR to provide custom handling when the application dies. This \fIerror()\fR routine provides a shortcut for displaying error messages to the user. So, they both have a place on their own, and it could make sense to use them together. In your 'error_mode' routine, you might call \fIerror()\fR to return a message to the user: .PP .Vb 1 \& $self\->error( title => \*(AqTechnical Failure\*(Aq, msg => \*(AqThere was a technical failure\*(Aq ); .Ve .SS "Suggested Uses" .IX Subsection "Suggested Uses" Some common cases for returning error messages to the user include: .PP .Vb 3 \& * "Technical Failure" \- The software failed unexpectedly \& * "Insufficient Information" \- some required query parameter was missing \& * "Request Not Understood" \- Some value we received in the query just didn\*(Aqt make sense. .Ve .SS "Silliness" .IX Subsection "Silliness" .Vb 2 \& [22:36] Techno Failure. We were cruising along and rocking out while fulfilling your request, but then the music stopped and we sort of got distracted. \& [22:36] Tek Failure. Too busy reading Shatner novels to respond to your request. .Ve .SH "METHODS" .IX Header "METHODS" .SS "\fIerror()\fP" .IX Subsection "error()" .Vb 4 \& return $self\->error( \& title => "Technical Failure\*(Aq, \& msg => "There was a techical failure during the operation", \& ); .Ve .PP Nothing fancy, just a shortcut to load a template meant to display errors. I've used it for the past several years, and it's been very handy to always have around on projects to quickly write error handling code. .PP It tries to load a template file named 'error.html' to display the error page. .PP If you want to use a different location, I recommend putting something like this in your base class, so you only have to provide your error template location once. .PP .Vb 9 \& # In this case, intentionally *don\*(Aqt* import \*(Aqerror\*(Aq to avoid a "redefined" warning. \& use CGI::Application::Plugin::ErrorPage; \& sub error { \& my $c = shift; \& return $c\->CGI::Application::Plugin::ErrorPage::error( \& tmpl => $self\->cfg(\*(AqROOT_URI\*(Aq).\*(Aq/path/to/my/alternate/error/file.html\*(Aq, \& @_, \& ); \& } .Ve .PP This module intentionally ignores any \f(CW\*(C`tmpl_path()\*(C'\fR set by application, since this is usually an indication of where the intended file is located, not the error template. This exceptional handling of the \f(CW\*(C`tmpl_path()\*(C'\fR is one of the only value added bits of logic that this plugin adds. The rest of it is primarily a simple recommendation for error page handling wrapped up as a module. .PP If you don't want this behavior, it's simple enough just to roll your own \fIerror()\fR page method and skip using this plugin. Here's the simple essential code: .PP .Vb 8 \& use Params::Validate \*(Aq:all\*(Aq; \& sub error { \& my $self = shift; \& my %p = validate(@_, { title => SCALAR, msg => SCALAR }); \& my $t = $self\->load_tmpl; \& $t\->param( title => $p{title}, msg => $p{msg} ); \& return $t\->output; \& } .Ve .SS "Example error.html" .IX Subsection "Example error.html" Here's a very basic example of an \f(CW\*(C`error.html\*(C'\fR file to get you started. .PP .Vb 10 \& \& \& \& <!\-\- tmpl_var title escape=HTML \-\-> \& \& \& \&

\&

\& \& .Ve .PP We manage site-wide designs with Dreamweaver and keep a basic 'error.html' that uses a generic Dreamweaver 'page.dwt' template with standard EditableRegion names. That way, we can copy this error.html into a new Dreamweaver-managed project and have the new design applied to it easily through Dreamweaver. .SH "SUPPORT" .IX Header "SUPPORT" Ask for help on the CGI::Application mailing list. Report bugs and wishes through the rt.cpan.org bug tracker. .SH "AUTHOR" .IX Header "AUTHOR" .Vb 3 \& Mark Stosberg \& CPAN ID: MARKSTOS \& mark@summersault.com .Ve .SH "COPYRIGHT" .IX Header "COPYRIGHT" This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP The full text of the license can be found in the \&\s-1LICENSE\s0 file included with this module. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIperl\fR\|(1).