Apache2::TX - Apache 2.x Output Filter based on the TX Perl module
<Perl>
use Apache2::TX;
$My::TX=Apache2::TX->new
(
TX parameters,
userdata=>...,
mixin=>[qw/names/],
mixin parameters,
);
</Perl>
PerlFixupHandler $My::TX->Fixup
Apache2::TX is an output filter ...
Inside a template the variable $TX::TX provided by the TX module keeps the Apache2::TX object. So, the current Apache2::RequestRec can be accessed as $TX::TX->r.
$TX::TX->r->pnotes->{original_uri} keeps the uri as it was at the beginning of the fixup phase before registered fixup handlers eventually modified it.
To fetch the parameters of another URI just issue a subrequest, set $subr->notes->{only_fetch_param} and run it:
my $subr=$TX::TX->r->lookup_uri($uri);
if( $subr->status==Apache2::Const::HTTP_OK ) {
$subr->notes->{only_fetch_param}=1;
$data=$subr->pnotes->{param}
if( $subr->run==Apache2::Const::OK );
}
Then fetch the data from $subr->pnotes->{param}.
While no output is yet written even a filter can change the request's status code and headers. So, a template can throw a special exception to generate a redirect (303) response for example.
To do that throw an Apache2::TX::Exception object:
die Apache2::TX::Exception->new
( type=>Apache2::TX::E_REDIRECT,
location=>'http://other.site/...' );
Keep in mind, this must happen before any output is generated.
The following special exception types are defined:
redirects the browser to an other URL. The URL is given as location parameter and according to RFC2612 must be complete including scheme, host and uri parts.
generates a 404 Not Found response.
generates a 500 Internal Server Error response.
generates a 400 Bad Request response.
generates a 401 Authorization Required response. The realm and type must be specified as www-authenticate parameter:
die Apache2::TX::Exception->new
( type=>Apache2::TX::E_AUTH,
'www-authenticate'=>'Basic realm="Area 51"' );
generates a 403 Forbidden response.
The following hooks are provided to allow mixins to interfere. A mixin doesn't have to implement all hooks or even any of them but it can.
The hooks are called in the order specified in the contructor call. If a mixin implements a hook but cannot provide data it should return undef or an empty list. Then the next mixin that implements the hook is called.
If no mixin can provide data the default action is taken.
currently the filter reads all data block into main memory before passing them onto the evaluator. This is likely to be changed when I figure out how to feed the perl interpreter one block at a time.
This hook allows mixins to process arbitrary data as long as it evaluates to (key,value) pairs. The default format is the output of
Data::Dumper::Dumper(\%data)
or
Data::Dumper->Dump([\%data], [qw(*VAR1)])
or
Data::Dumper::Dumper([%data])
or
Data::Dumper->Dump([[%data]], [qw(*VAR1)])
That means all of the following is valid input:
$VAR1={'KEY'=>'VALUE'};
$VAR1=['KEY', 'VALUE'];
@VAR1=('KEY', 'VALUE');
%VAR1=('KEY'=>'VALUE');
The resulting list is converted into a HASH called %param.
If your mixin cannot provide data return an empty list.
By default the template is fetched from the %param HASH by the key template. This hook allows the mixin to override that. As result a template name is expected. If your mixin cannot provide a template name simply don't implement this hook or return undef or an empty string.
Torsten Förtsch, <torsten.foertsch@gmx.net>
Copyright (C) 2009-2010 by Torsten Foertsch
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.