view release on metacpan or  search on metacpan

lib/Plack/Middleware/TazXSLT.pm  view on Meta::CPAN

                $ret = $write;
                return;
            }
        }
    );
    return $ret;
}

1;

__END__

=head1 NAME 

Plack::Middleware::TazXSLT - transform xml documents by applying xsl stylesheets on the fly

=head1 DESCRIPTION

Plack::Middleware::TazXSLT is an plack aware middleware that transforms
xml documents by applying xsl stylesheets on the fly. It was developed to
serve an replacement for the L<http://modxslt.org/> as its development
seems stalled for a long time. When using the word replacement please
keep in mind that it is not really a drop in alternative for modxslt,
as it just implements a very basic subset of modxslts functionality.

Every time the plack backend return a response to
Plack::Middleware::TazXSLT it checks if the response is successful,
not a redirect, not a HEAD request, has content and is actually a xml
document. If all that applies, it parses the xml document and applies
the supplied stylesheet to it.

There are two way to communicate which stylesheet to use. If
the response returned by the application contains the HTTP header
X-Taz-XSLT-Stylesheet, it's value is expected to be an URL pointing to
an XSLT stylesheet which is than downloaded and applied. If the response
misses this header, Plack::Middleware::TazXSLT tries to find a processing
instruction of type of I<text/xsl>:

  <?modxslt-stylesheet 
    type="text/xsl" 
    href="http://$HEADER[Host]/$HEADER[X-Taz-Base]/base.xsl" ?>

All occurrences of $HEADER[] in its I<href> attribute are replaced the
the values from the backends http response.

=head1 SYNOPSIS

  my $app = builder {
    enable "TazXSLT";
    Plack::App::Proxy->new( backend => 'LWP', remote => 'http://example.com/ )->to_app;
  };

=head1 ATTRIBUTES

=over 4

=item user_agent

HTTP user agent to fetch the the necessary stylesheets. Defaults to
an LWP::UserAgent with its timeout set to I<timeout> seconds and act
according to the environment variables HTTP_PROXY and HTTPS_PROXY.

It is possible to provide an useragent object of another class as long
as it respond to a call of I<get> and returns an object that provides
the method calls I<is_redirect>, I<is_success>, I<content_length>,
I<content_length>, I<content_is_xml> and behaves semantically similar
to LWPs HTTP::Reponse.

=item xml_parser

An instance of XML::LibXML. Defaults to the following simple call:

  XML::LibXML->new();

=item xslt_parser

An instance of XML::LibXSLT. Defaults to the following simple call:

  XML::LibXSLT->new();

=item name

A string with is accessible via the xslt variable
I<modxslt-name>. Defaults to I<tazxslt>.

=item timeout

Timeout for http connections this objects I<user_agent>
attribute. Defaults to 180 seconds.

=item log_filter

A subroutine reference that is called with the error message as
its only argument every time libxml is not able to parse the xml
document. Unfortunately libxml returns multiline error messages with
indentation. This defaults to the function I<parse_libxml_error> that
strips the string of all newlines and replaces consecutive whitespace
characters into one space character.

=back

=head1 ENVIRONMENT

=over 4

=item TAZ_XSLT_PROFILE

If this environment variable is set to a true value, every call to
apply_transformation is profiled and the result will be printed to
wherever I<$env-E<gt>{'psgi.errors'}> is pointing.

  [http://example.com] xslt-processing-time: 0.01245

=back

=head1 SEE ALSO

L<http://modxslt.org/>, L<https://metacpan.org/module/Plack::Middleware::XSLT>