1CGI::Application::PlugiUns:e:rErCroonrtPraigbeu(t3e)d PeCrGlI:D:oAcpupmleinctaattiioonn::Plugin::ErrorPage(3)
2
3
4

NAME

6       CGI::Application::Plugin::ErrorPage - A simple error page plugin for
7       CGI::Application
8

SYNOPSIS

10         use CGI::Application::Plugin::ErrorPage 'error';
11
12         sub my_run_mode {
13           my $self = shift;
14
15           eval { .... };
16
17           if ($@) {
18               # Send the gory details to the log for the developers
19               warn "$@";
20
21               # Send a comprehensible message to the users
22               return $self->error(
23                   title => "Technical Failure',
24                   msg   => "There was a techical failure during the operation.",
25               );
26           }
27
28         }
29

DESCRIPTION

31       This plugin provides a shortcut for the common need of returning a
32       simple error message to the user.
33
34       You are encouraged to provide a template file so that the error
35       messages can be presented with a design consistent with the rest of
36       your application.
37
38       A simple design is provided below to get to you started.
39
40   A better default error page.
41       If you don't install an AUTOLOAD run mode in the normal way in "setup",
42       this plugin will automatically install a reasonable default at the
43       "prerun" stage, which returns an error page like this:
44
45         return $c->error(
46             title => 'The requested page was not found.',
47             msg => "(The page tried was: ".$c->get_current_runmode.")"
48         );
49
50   Relation to error_mode()
51       CGI::Application includes "error_mode()" to provide custom handling
52       when the application dies.  This error() routine provides a shortcut
53       for displaying error messages to the user. So, they both have a place
54       on their own, and it could make sense to use them together. In your
55       'error_mode' routine, you might call error() to return a message to the
56       user:
57
58           $self->error( title => 'Technical Failure', msg => 'There was a technical failure' );
59
60   Suggested Uses
61       Some common cases for returning error messages to the user include:
62
63         * "Technical Failure" - The software failed unexpectedly
64         * "Insufficient Information" - some required query parameter was missing
65         * "Request Not Understood" - Some value we received in the query just didn't make sense.
66
67   Silliness
68         [22:36] <rjbs> Techno Failure.  We were cruising along and rocking out while fulfilling your request, but then the music stopped and we sort of got distracted.
69         [22:36] <rjbs> Tek Failure.  Too busy reading Shatner novels to respond to your request.
70

METHODS

72   error()
73               return $self->error(
74                   title => "Technical Failure',
75                   msg   => "There was a techical failure during the operation",
76               );
77
78       Nothing fancy, just a shortcut to load a template meant to display
79       errors. I've used it for the past several years, and it's been very
80       handy to always have around on projects to quickly write error handling
81       code.
82
83       It tries to load a template file named 'error.html' to display the
84       error page.
85
86       If you want to use a different location, I recommend putting something
87       like this in your base class, so you only have to provide your error
88       template location once.
89
90        # In this case, intentionally *don't* import 'error' to avoid a "redefined" warning.
91        use CGI::Application::Plugin::ErrorPage;
92        sub error {
93             my $c = shift;
94             return $c->CGI::Application::Plugin::ErrorPage::error(
95                 tmpl => $self->cfg('ROOT_URI').'/path/to/my/alternate/error/file.html',
96                 @_,
97             );
98        }
99
100       This module intentionally ignores any "tmpl_path()" set by application,
101       since this is usually an indication of where the intended file is
102       located, not the error template.  This exceptional handling of the
103       "tmpl_path()" is one of the only value added bits of logic that this
104       plugin adds. The rest of it is primarily a simple recommendation for
105       error page handling wrapped up as a module.
106
107       If you don't want this behavior, it's simple enough just to roll your
108       own error() page method and skip using this plugin. Here's the simple
109       essential code:
110
111           use Params::Validate ':all';
112           sub error {
113               my $self  = shift;
114               my %p = validate(@_, { title => SCALAR, msg => SCALAR });
115               my $t = $self->load_tmpl;
116               $t->param( title => $p{title}, msg => $p{msg} );
117               return $t->output;
118           }
119
120   Example error.html
121       Here's a very basic example of an "error.html" file to get you started.
122
123        <!DOCTYPE html
124                PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
125                 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
126        <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US">
127        <head>
128        <title><!-- tmpl_var title escape=HTML --></title>
129        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
130        </head>
131        <body>
132        <h1><!-- tmpl_var title escape=HTML--></h1>
133        <p><!-- tmpl_var msg escape=HTML --></p>
134        </body>
135        </html>
136
137       We manage site-wide designs with Dreamweaver and keep a basic
138       'error.html' that uses a generic Dreamweaver 'page.dwt' template with
139       standard EditableRegion names. That way, we can copy this error.html
140       into a new Dreamweaver-managed project and have the new design applied
141       to it easily through Dreamweaver.
142

SUPPORT

144       Ask for help on the CGI::Application mailing list. Report bugs and
145       wishes through the rt.cpan.org bug tracker.
146

AUTHOR

148           Mark Stosberg
149           CPAN ID: MARKSTOS
150           mark@summersault.com
151
153       This program is free software; you can redistribute it and/or modify it
154       under the same terms as Perl itself.
155
156       The full text of the license can be found in the LICENSE file included
157       with this module.
158

SEE ALSO

160       perl(1).
161
162
163
164perl v5.34.0                      2021-07C-G2I2::Application::Plugin::ErrorPage(3)
Impressum