NAME

Plack::Debugger::Panel - Base class for the debugger panels

VERSION

version 0.03

DESCRIPTION

This is the base class for all the Plack::Debugger panels, most of the subclasses of this module will simply pass in a set of custom arguments to the constructor and not much more.

METHODS

new (%args)

This will look in %args for a number of values, technically there are no required keys, but the code won't do very much if you don't give it anything.

This accepts the title key, which is a string to display on the debugger UI, it will default to something generated with refaddr, but it is better to specify it.

This accepts the subtitle key, which is also displayed in the debugger UI and can be used to present additional data to the user, it defaults to an empty string.

This accepts the before, after and cleanup callbacks and checks to make sure that they are all CODE references.

This accepts the formatter key, this is a string that is passed to the debugger UI via the metadata to tell the UI how to render the data that is stored in the result of the panel.

This accepts the metadata key, this is a HASH reference that is passed to the debugging UI. The types of keys accepted are determined by the debugger UI and what it handles. See the docs for metadata below for information on those keys.

title

Simple read accessor for the title.

subtitle

Simple read accessor for the subtitle.

set_subtitle ($subtitle)

Simple write accessor for the subtitle.

run_before_phase ($env)

This will run the before callback and mark that phase as having been run.

run_after_phase ($env, $resp)

This will run the after callback and mark that phase as having been run. This phase will only run if the before phase has also been run, since it may have stashed data that is needed by this phase.

run_cleanup_phase ($env)

This will run the cleanup callback and mark that phase as having been run. This phase will only run if the before and after phases have also been run, since they may have stashed data that is needed by this phase.

mark_phase_as_run ($phase)

Marks a phase as having been run.

mark_phase_as_not_run ($phase)

Marks a phase as having not been run.

have_phases_run (@phases)

This predicate will return true if all the @phases specified have been marked as run.

before

Simple read accessor for the before callback.

has_before

Simple predicate to determine if we have a before callback.

after

Simple read accessor for the after callback.

has_after

Simple predicate to determine if we have an after callback.

cleanup

Simple read accessor for the cleanup callback.

has_cleanup

Simple predicate to determine if we have a cleanup callback.

notify ($type, ?$inc)

This method can be used to mark a panel specific event as having happened during the request and the user should be notified about. The $type argument must match one of the strings in the NOTIFICATION_LEVELS constant, which are basically; success, warning or error. The optional $inc argument can be used to mark more then one event of the specified $type as having happened. If $inc is not specified then a value of 1 is assumed.

has_notifications

Simple predicate to determine if we have any notifications.

notifications

Simple read accessor for the notification data.

add_metadata ($key, $data)

Sets the metadata $key to $data.

has_metadata

Simple predicate to tell if we have any metadata available.

metadata

Simple accessor for the metadata that is passed back to the debugger UI about this particular panel. There is no specific set of acceptable keys for this, but the UI currently only understands the following:

formatter

This can be optionally specifed via the formatter constructor parameter, see the docs for new for more details on this.

track_subrequests

This is used to tell the debugging UI that it should start tracking AJAX requests.

highlight_on_warnings

This is used to tell the debugging UI that it should highlight the UI elements associated with this panel when there are any warning notifications.

highlight_on_errors

This is used to tell the debugging UI that it should highlight the UI elements associated with this panel when there are any error notifications.

is_subrequest ($env)

This looks at the PSGI $env to determine if the current request is actually a sub-request. This is primarily used in panels to disable themselves in a subrequest if it is not appropriate for it to run.

disable

This sets a flag to disable the panel for this particular request.

is_disabled

Simple predicate to determine if the panel is disabled or not.

enable

This sets a flag to enable the panel for this particular request.

is_enabled

Simple predicate to determine if the panel is enabled or not.

stash (?$data)

This is just a simple read/write accessor for a general purpose stash that can be used to pass data in between the various phases of the panel.

get_result

This is a read accessor for the final result data for the panel.

set_result ($result)

This is a write accessor for the final result data for the panel.

reset

This method will be called at the end of a request to reset all the panel data so it can be ready for the next run. It will aggressively delete the stash and result data to avoid the possibility of leaking memory, after that it will result some internal book keeping data (enabled flag, notifications and list of phases that have been run).

ACKNOWLEDGMENT

This module was originally developed for Booking.com. With approval from Booking.com, this module was generalized and published on CPAN, for which the authors would like to express their gratitude.

AUTHOR

Stevan Little <stevan@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Stevan Little.

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