NAME

MasonX::CallbackHandle - Callback Requst Data and Utility Methods

SYNOPSIS

sub my_callback {
    my $cbh = shift;
    my $args = $cbh->request_args;
    my $value = $cbh->value;
    # Do stuff with above data.
    $cbh->redirect($url);
}

DESCRIPTION

MasonX::CallbackHandle objects are constructed by MasonX::ApacheHandler::WithCallbacks and passed in as the sole argument for every execution of a callback code reference. See MasonX::ApacheHandler::WithCallbacks for details on how to configure it to execute your callback code.

INTERFACE

MasonX::CallbackHandle objects are created by MasonX::ApacheHandler::WithCallbacks, and should never be constructed directly. However, you'll find them very useful when they're passed to your callback code references. Here's a listing of the goodies you'll find.

Accessor Methods

All of the MasonX::CallbackHandle accessor methods are read-only.

ah

my $ah = $cbh->ah;

Returns a reference to the MasonX::ApacheHandler::WithCallbacks object that executed the callback.

request_args

my $args = $cbh->request_args;

Returns a reference to the Mason request arguments hash. This is the hash that will be used to create the %ARGS hash and the <%args> block variables in your Mason components. Any changes you make to this hash will percolate back to your components.

apache_req

my $r = $cbh->apache_req;

Returns the Apache request object for the current request. If you've told Mason to use Apache::Request, it is the Apache::Request object that will be returned. Otherwise, if you're having CGI process your request arguments, then it will be the plain old Apache object.

priority

my $priority = $cbh->priority;

Returns the priority level at which the callback was executed. Possible values are between "0" and "9".

cb_key

my $cb_key = $cbh->cb_key;

Returns the callback key that triggered the execution of the callback. For example, this callback-triggering form field:

<input type="submit" value="Save" name="DEFAULT|save_cb" />

Will cause the cb_key() method in the relevant callback to return "save".

pkg_key

my $pkg_key = $cbh->pkg_key;

Returns the package key used in the callback trigger field. For example, this callback-triggering form field:

<input type="submit" value="Save" name="MyCBs|save_cb" />

Will cause the pkg_key() method in the relevant callback to return "MyCBs".

value

my $value = $cbh->value;

Returns the value of the callback trigger field. If there is more than one value for the callback trigger field, then value() will return an array reference. For examle, for this callback field:

<input type="hidden" value="foo" name="DEFAULT|save_cb" />

the value returned by value() will be "foo". For this example, however:

<input type="hidden" value="foo" name="DEFAULT|save_cb" />
<input type="hidden" value="bar" name="DEFAULT|save_cb" />

value() will return the two-element array reference ['foo', 'bar']. If you override the priority, however, or if the fields have different priorities, then you can expect the callback to be called twice. For example, these form fields:

<input type="hidden" value="foo" name="DEFAULT|save_cb3" />
<input type="hidden" value="bar" name="DEFAULT|save_cb2" />

will cause the relevant callback to be called twice. The first time, value() will return "bar", and the second time, it will return "foo".

Although you may often be able to retrieve the value directly from the hash reference returned by request_args(), if multiple callback keys point to the same subroutine or if the form overrode the priority, you may not be able to figure which value or values were submitted for a particular callback execution. So MasonX::CallbackHandle nicely provides the value or values for you.

trigger_key

my $trigger_key = $cbh->trigger_key;

Returns the request argument key that triggered the callback. This is the complete name used in the HTML field that triggered the callback. For example, if the field that triggered the callback looks like this:

<input type="submit" value="Save" name="MyCBs|save_cb6" />

then the value returned by trigger_key() method will be "MyCBs|save_cb6".

Note: Most browers will submit "image" input fields with two arguments, one with ".x" appended to its name, and the other with ".y" appended to its name. MasonX:::ApacheHandler::WithCallbacks will ignore these fields and either use the field named without the ".x" or ".y", or create a field with that name and give it a value of "1". The reasoning behind this approach is that the names of the callback-triggering fields should be the same as the names that appear in the form fields.

redirected

$cbh->redirect($url) unless $cbh->redirected;

If the request has been redirected, this method returns the rediretion URL. Otherwise, it eturns false. This method is useful for conditions in which one callback has called $cbh->redirect with the optional $wait argument set to a true value, thus allowing subsequent callbacks to continue to execute. If any of those subsequent callbacks want to call $cbh->redirect themselves, they can check the value of $cbh->redirected to make sure it hasn't been done already.

Other Methods

The MasonX::CallbackHandle object has a few other publicly accessible methods.

redirect

$cbh->redirect($url);
$cbh->redirect($url, $status);
$cbh->redirect($url, $status, $wait);

Given a URL, this method generates a proper HTTP redirect for that URL. By default, the status code used is "302", but this can be overridden via the $status argument. If the optional $wait argument is true, any callbacks scheduled to be executed after the call to redirect will continue to be executed. In that clase, $cbh->abort will not be called; rather, MasonX::ApacheHandler::WithCallbacks will finish executing all remaining callbacks and then check the status and abort before Mason creates and executes a component stack. If the $wait argument is unspecified or false, then the request will be immediately terminated without executing subsequent callbacks or, of course, any Mason components. This approach relies on the execution of $cbh->abort.

Since by default $cbh->redirect calls $cbh->abort, it will be trapped by an eval {} block. If you are using an eval {} block in your code to trap errors, you need to make sure to rethrow these exceptions, like this:

eval {
    ...
};

die $@ if $cbh->aborted;

# handle other exceptions

abort

$cbh->abort($status);

Ends the current request without executing any more callbacks or any Mason components. The $status argument specifies the HTTP request status code to be returned to Apache.

abort is implemented by throwing an HTML::Mason::Exception::Abort object and can thus be caught by eval(). The aborted method is a shortcut for determining whether a caught error was generated by abort.

aborted

die $err if $cbh->aborted;
die $err if $cbh->aborted($err);

Returns true or undef indicating whether the specified $err was generated by abort. If no $err argument is passed, aborted examines $@, instead.

In this code, we catch and process fatal errors while letting abort exceptions pass through:

eval { code_that_may_fail_or_abort() };
if ($@) {
    die $@ if $cbh->aborted;

    # handle fatal errors...
}

$@ can lose its value quickly, so if you're planning to call $cbh->aborted more than a few lines after the eval, you should save $@ to a temporary variable and pass it explicitly via the $err argument.

SEE ALSO

MasonX::ApacheHandler::WithCallbacks constructs MasonX::CallbackHandle objects and passes them as the sole argument to callback code references.

AUTHOR

David Wheeler <david@wheeler.net>

COPYRIGHT AND LICENSE

Copyright 2003 by David Wheeler

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