Index of /darcs_hive/darcs_hive/ca-callbacks

 Name                    Last modified       Size  Description

 Parent Directory        10-Aug-2009 20:00      -  
 Build.PL                19-Dec-2004 14:19     1k  
 Changes                 19-Dec-2004 14:19     1k  
 MANIFEST                19-Dec-2004 14:19     1k  
 META.yml                19-Dec-2004 14:19     1k  
 Makefile.PL             19-Dec-2004 14:19     1k  
 _darcs/                 19-Dec-2004 14:19      -  
 lib/                    19-Dec-2004 14:19      -  
 t/                      19-Dec-2004 14:19      -  

NAME
    CGI::Application::Callbacks

    This module extends CGI::Application by adding support for registering
    multiple callbacks at different stages of execution. It can be used in
    place of CGI::Application, and will work as a drop in replacement.

    It is possible that the features in this module may one day be included
    in the core of CGI::Application, making this module redundant. Please
    watch the Changes file after any upgrades.

SYNOPSIS
      # register a callback to the standard CGI::Application hooks
      #   one of 'init', 'prerun', 'postrun' or 'teardown'
      $self->add_callback('prerun', \&callback);
      $self->add_callback('teardown', \&callback, 'FIRST');

      # Create a new hook
      $self->new_hook('pretemplate');
  
      # register a callback to this hook
      $self->add_callback('pretemplate', \&callback);

      # Then later execute all the callbacks registered at this hook
      $self->call_hook('pretemplate');

DESCRIPTION
    CGI::application is designed to be extendable by allowing the developer
    to override several methods that are executed at different stages of
    execution. These include the cgiapp_init, cgiapp_prerun, cgiapp_postrun
    and teardown methods (please see the CGI::Application documentation for
    the use of these methods).

    One major issue with the way CGI::Application works with these methods,
    is that only one subroutine can be executed at each of these stages.
    With many people using Base classes for their applications, and the
    number of CGI::Application plugins appearing on CPAN, it can be useful
    to be able to have multiple cgiapp_prerun methods.

    This module aims to solve this problem by allowing the developer to add
    multiple callbacks at any of the four default stages defined in
    CGI::Application. This means you can have some code in your Base class
    run at the prerun stage, as well as some more code in your runmode class
    also running at the prerun stage, and a plugin could have a third bit of
    code running at the prerun stage.

    Another benefit is the ability to create a new hook where callbacks can
    be registered. For example a template plugin coule create a
    'pretemplate' hook. Any callbacks registered at this stage could then be
    executed before any template gets loaded or processed. This is achieved
    through the new_hook and call_hook methods.

  Methods
    The following methods are implemented in this module:

    add_callback(HOOK, CALLBACK, ORDER)
            $self->add_callback('teardown', \&callback, 'FIRST');

        The add_callback method allows you to register a callback function
        that is to be called at the given stage of execution. Valid hooks
        include 'init', 'prerun', 'postrun' and 'teardown', and possible a
        new hook defined using the new_hook method.

        The callback should be a reference to a subroutine. The order is
        optional, and gives an indication of the order in which the
        callbacks should be executed. Valid values for the order are
        'FIRST', 'MIDDLE' (default), 'LAST', and two special orders
        'REALLY_FIRST' and 'REALLY_LAST'. If multiple callbacks are added to
        the same order for the same hook, they will be executed in the order
        they were registered. The REALLY_FIRST and REALLY_FIRST orders can
        only be used once per hook and should only be used in special
        circumstances where it is critical that the method should be
        executed first or last.

    new_hook(HOOK)
            $self->new_hook('pretemplate');

        The new_hook method can be used to create a new hook location. This
        can be a new stage for developers to register new callbacks. It
        works in conjunction with call_hook which will execute the callbacks
        registered at the new hook.

        It can be useful for plugin authors who want to new hook for
        developers to use. See the CGI::Application::Plugin::TT for an
        example of a new hook that is executed before and after every
        template that is processed.

    call_hook(HOOK)
            $self->call_hook('pretemplate');

        The call_hook method is used to executed the callbacks that have
        been registered at the given hook. It is used in conjunction with
        the new_hook method which allows you to create a new hook location.

SEE ALSO
    CGI::Application, CGI::Application::Plugin::TT, perl(1)

AUTHOR
    Cees Hek <cees@crtconsulting.ca>

LICENSE
    Copyright (C) 2004 Cees Hek <cees@crtconsulting.ca>

    This library is free software. You can modify and or distribute it under
    the same terms as Perl itself.