NAME
    CGI::Application::Plugin::DevPopup - Runtime cgiapp info in a popup
    window

VERSION
    Version 0.92

SYNOPSIS
  End user information
    This module provides a plugin framework for displaying runtime
    information about your CGI::Application app in a popup window. A sample
    Timing plugin is provided to show how it works:

        BEGIN { $ENV{'CAP_DEVPOPUP_EXEC'} = 1; } # turn it on for real
        use CGI::Application::Plugin::DevPopup;
        use CGI::Application::Plugin::DevPopup::Timing;

        The rest of your application follows
        ...

    Now whenever you access a runmode, a window pops up over your content,
    showing information about how long the various stages have taken. Adding
    other CAP::DevPopup plugins will get you more information. A HTML::Tidy
    plugin showing you how your document conforms to W3C standards is
    available: seer CGI::Application::Plugin::HtmlTidy.

    The output consists of a Table of Contents, and a bunch of reports. A
    rough translation into plain text could look like this:

        Devpopup report for My::App -> add_timing

        * Timings - Total runtime: 3.1178 sec.

        +-----------------------------------------------------------------------+
        | Timings                                                               |
        +-----------------------------------------------------------------------+
        | Application started at: Thu Sep 22 02:55:35 2005                      |
        | From                       To                         Time taken      |
        |-----------------------------------------------------------------------|
        | init                       prerun                     0.107513 sec.   |
        | prerun                     before expensive operation 0.000371 sec.   |
        | before expensive operation after expensive operation  3.006688 sec.   |
        | after expensive operation  load_tmpl(dp.html)         0.000379 sec.   |
        | load_tmpl(dp.html)         postrun                    0.002849 sec.   |
        +-----------------------------------------------------------------------+

    The reports expand and collapse by clicking on the ToC entry or the
    report header.

    You can see a (developer) version in action here:
    <http://oss.rhesa.com/scripts/dp.cgi>, and the same script with the
    plugin turned off at <http://oss.rhesa.com/scripts/dp_off.cgi>.

  Developer information
    Creating a new plugin for DevPopup is fairly simple. CAP::DevPopup
    registers a new callback point (named "devpopup_report"), which it uses
    to collect output from your plugin. You can add a callback to that
    point, and return your formatted output from there. The callback has
    this signature:

        sub callback($cgiapp_class, $outputref)

    You pass your output to the devpopup object by calling

        $cgiapp_class->devpopup->add_report(
                    title   => $title,
                    summary => $summary,
                    report  => $body
        );

    You are receiving $outputref, because DevPopup wants to be the last one
    to be called in the postrun callback. If you had wanted to act at
    postrun time, then please do so with this variable, and not through a
    callback at postrun.

  The "on" switch
    Since this is primarily a development plugin, and you wouldn't want it
    to run in your production code, an environment variable named
    CAP_DEVPOPUP_EXEC has to be set to 1 for this module to function.
    Absense of the environment variable turns this module into a no-op:
    while the plugin and its plugins are still loaded, they won't modify
    your output.

Available Plugins
    o   CGI::Application::Plugin::DevPopup::Timing and
        CGI::Application::Plugin::DevPopup::HTTPHeaders are bundled with
        this distribution.

    o   CGI::Application::Plugin::HtmlTidy integrates with this module.

    o   CGI::Application::Plugin::TT integrates with this module.

EXPORTS
    * devpopup
        This method is the only one exported into your module, and can be
        used to access the underlying DevPopup object. See below for the
        methods that this object exposes.

METHODS
    * add_report( %fields )
        Adds a new report about the current run of the application. The
        following fields are supported:

        * title A short title for your report

        * summary
                An optional one- or two-line summary of your findings

        * report
                Your full output

        * script
                If you have custom javascript, then please pass it in
                through this field. Otherwise if it's embedded in your
                report, it will break the popup window. I will take care of
                the surrounding "<script"> tags, so just the code body is
                needed.

INSTALLATION
    INSTALLATION

    To install this module, run:

        cpan CGI::Application::Plugin::DevPopup

    To mnually install this module, run the following commands:

        perl Makefile.PL
        make
        make test
        make install

SEE ALSO
    CGI::Application. CGI::Application::Plugin::DevPopup::Timing

AUTHOR
    Rhesa Rozendaal, rhesa@cpan.org

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

ACKNOWLEDGEMENTS
    Mark Stosberg for the initial idea, and for pushing me to write it.
    Sam Tregar for providing me with the skeleton cgiapp_postrun.
    Everybody on the cgiapp mailinglist and on #cgiapp for cheering me on
    :-)

COPYRIGHT & LICENSE
    Copyright 2005 Rhesa Rozendaal, all rights reserved.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.