1CGI::Application::PlugiUns:e:rDeCvoPnotpruipb(u3t)ed PerClGID:o:cAupmpelnitcaattiioonn::Plugin::DevPopup(3)
2
3
4

NAME

6       CGI::Application::Plugin::DevPopup - Runtime cgiapp info in a popup
7       window
8

VERSION

10       version 1.08
11

SYNOPSIS

13   End user information
14       This module provides a plugin framework for displaying runtime
15       information about your CGI::Application app in a popup window. A sample
16       Timing plugin is provided to show how it works:
17
18           BEGIN { $ENV{'CAP_DEVPOPUP_EXEC'} = 1; } # turn it on for real
19           use CGI::Application::Plugin::DevPopup;
20           use CGI::Application::Plugin::DevPopup::Timing;
21
22           The rest of your application follows
23           ...
24
25       Now whenever you access a runmode, a window pops up over your content,
26       showing information about how long the various stages have taken.
27       Adding other CAP::DevPopup plugins will get you more information. A
28       HTML::Tidy plugin showing you how your document conforms to W3C
29       standards is available: see CGI::Application::Plugin::HtmlTidy.
30
31       The output consists of a Table of Contents, and a bunch of reports. A
32       rough translation into plain text could look like this:
33
34           Devpopup report for My::App -> add_timing
35
36           * Timings - Total runtime: 3.1178 sec.
37
38           +-----------------------------------------------------------------------+
39           | Timings                                                               |
40           +-----------------------------------------------------------------------+
41           | Application started at: Thu Sep 22 02:55:35 2005                      |
42           | From                       To                         Time taken      |
43           |-----------------------------------------------------------------------|
44           | init                       prerun                     0.107513 sec.   |
45           | prerun                     before expensive operation 0.000371 sec.   |
46           | before expensive operation after expensive operation  3.006688 sec.   |
47           | after expensive operation  load_tmpl(dp.html)         0.000379 sec.   |
48           | load_tmpl(dp.html)         postrun                    0.002849 sec.   |
49           +-----------------------------------------------------------------------+
50
51       The reports expand and collapse by clicking on the ToC entry or the
52       report header.
53
54   Developer information
55       Creating a new plugin for DevPopup is fairly simple. CAP::DevPopup
56       registers a new callback point (named "devpopup_report"),  which it
57       uses to collect output from your plugin. You can add a callback to that
58       point, and return your formatted output from there. The callback has
59       this signature:
60
61           sub callback($cgiapp_class, $outputref)
62
63       You pass your output to the devpopup object by calling
64
65           $cgiapp_class->devpopup->add_report(
66                       title   => $title,
67                       summary => $summary,
68                       report  => $body,
69           );
70
71       You are receiving $outputref, because DevPopup wants to be the last one
72       to be called in the postrun callback. If you had wanted to act at
73       postrun time, then please do so with this variable, and not through a
74       callback at postrun.
75
76   The "on" switch
77       Since this is primarily a development plugin, and you wouldn't want it
78       to run in your production code, an environment variable named
79       CAP_DEVPOPUP_EXEC has to be set to 1 for this module to function, and
80       it must be present at compile time. This means you should place it in a
81       BEGIN{} block, or use SetEnv or PerlSetEnv (remember to set those
82       before any PerlRequire or PerlModule lines).
83
84       Absence of the environment variable turns this module into a no-op:
85       while the plugin and its plugins are still loaded, they won't modify
86       your output.
87

Available Plugins

89       o CGI::Application::Plugin::DevPopup::Timing,
90       CGI::Application::Plugin::DevPopup::Log and
91       CGI::Application::Plugin::DevPopup::HTTPHeaders are bundled with this
92       distribution.
93       o CGI::Application::Plugin::HtmlTidy integrates with this module.
94       o CGI::Application::Plugin::TT integrates with this module.
95

EXPORTS

97       •   devpopup
98
99           This method is the only one exported into your module, and can be
100           used to access the underlying DevPopup object. See below for the
101           methods that this object exposes.
102

METHODS

104       •   add_report( %fields )
105
106           Adds a new report about the current run of the application. The
107           following fields are supported:
108
109           •       title
110
111                   A short title for your report
112
113           •       summary
114
115                   An optional one- or two-line summary of your findings
116
117           •       report
118
119                   Your full output
120
121           •       severity
122
123                   An optional value specifying the importance of your report.
124                   Accepted values are qw/debug info warning error fatal/.
125                   This value is used to color-code the report headers.
126
127           •       script
128
129                   If you have custom javascript, then please pass it in
130                   through this field.  Otherwise if it's embedded in your
131                   report, it will break the popup window. I will take care of
132                   the surrounding "<script"> tags, so just the code body is
133                   needed.
134

INSTALLATION

136       INSTALLATION
137
138       To install this module, run:
139
140           cpan CGI::Application::Plugin::DevPopup
141
142       To mnually install this module, run the following commands:
143
144           perl Makefile.PL
145           make
146           make test
147           make install
148

SEE ALSO

150       CGI::Application. CGI::Application::Plugin::DevPopup::Timing
151

AUTHOR

153       Rhesa Rozendaal, rhesa@cpan.org
154

BUGS

156       Please report any bugs or feature requests to
157       bug-cgi-application-plugin-devpopup@rt.cpan.org, or through the web
158       interface at
159       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-Application-Plugin-DevPopup>.
160       I will be notified, and then you'll automatically be notified of
161       progress on your bug as I make changes.
162

ACKNOWLEDGEMENTS

164       Mark Stosberg for the initial idea, and for pushing me to write it.
165       Sam Tregar for providing me with the skeleton cgiapp_postrun.
166       Joshua Miller for providing the ::Log plugin.
167       Everybody on the cgiapp mailinglist and on #cgiapp for cheering me on
168       :-)
169
171       Copyright 2005-2007 Rhesa Rozendaal, all rights reserved.
172
173       This program is free software; you can redistribute it and/or modify it
174       under the same terms as Perl itself.
175
176
177
178perl v5.38.0                      2023-07-C2G0I::Application::Plugin::DevPopup(3)
Impressum