/ 
Catalyst-View-Wkhtmltopdf-0.5.2
River stage zero No dependents
/ Catalyst::View::Wkhtmltopdf

NAME

Catalyst::View::Wkhtmltopdf - Catalyst view to convert HTML (or TT) content to PDF using wkhtmltopdf

SYNOPSIS

# lib/MyApp/View/Wkhtmltopdf.pm
package MyApp::View::Wkhtmltopdf;
use Moose;
extends qw/Catalyst::View::Wkhtmltopdf/;
__PACKAGE__->meta->make_immutable();
1;

# configure in lib/MyApp.pm
MyApp->config({
  ...
  'View::Wkhtmltopdf' => {
      command   => '/usr/local/bin/wkhtmltopdf',
      # Guessed via File::Spec by default
      tmpdir    => '/usr/tmp',
      # Name of the Template view, "TT" by default
      tt_view   => 'Template',
  },
});

sub ciao : Local {
    my($self, $c) = @_;
    
    # Pass some HTML...
    $c->stash->{wk} = {
        html    => $web_page,
    };
    
    # ..or a TT template
    $c->stash->{wk} = {
        template    => 'hello.tt',
        page_size   => 'a5',
    };

    # More parameters...
    $c->stash->{wk} = {
        html        => $web_page,
        disposition => 'attachment',
        filename    => 'mydocument.pdf',
    };
    
    $c->forward('View::Wkhtmltopdf');
}

DESCRIPTION

Catalyst::View::Wkhtmltopdf is a Catalyst view handler that converts HTML data to PDF using wkhtmltopdf (which must be installed on your system). It can also handle direct conversion of TT templates (via Catalyst::View::TT).

CONFIG VARIABLES

All configuration parameters are optional as they have a default.

stash_key

The stash key which contains data and optional runtime configuration to pass to the view. Default is wk.

tmpdir

Default: guessed via File::Spec::tmpdir().

Name of URI parameter to specify JSON callback function name. Defaults to callback. Only effective when allow_callback is turned on.

command

Default: /usr/bin/wkhtmltopdf.

The full path and filename to the wkhtmltopdf command. Defaults to /usr/bin/wkhtmltopdf.

allows

Default: the temporary directory.

An arrayref of allowed paths where wkhtmltopdf can find images and other linked content. The temporary directory is added by default. See wkhtmltopdf documentation for more information.

disposition

Default: inline.

The content-disposition to set when sending the PDF file to the client. Can be either inline or (default) attachment.

filename

Default: output.pdf.

The filename to send to the client.

page_size

Default: A4.

Page size option. See wkhtmltopdf documentation for more information.

orientation

Default: portrait.

Orientation option. See wkhtmltopdf documentation for more information.

PARAMETERS

Parameters are passed fvia the stash:

$c->stash->{wkhtmltopdf} = {
    html    => $web_page,
};

You can pass the following configuration options here, which will override the global configuration: disposition, filename, page_size.

Other options currently supported are:

page-width, page-height

Width and height of the page, overrides page_size.

margin-top, margin-right, margin-bottom, margin-left

Margins, specified as 3mm, 0.7in, ...

Have a look at wkhtmltopdf documentation for more information regarding these options.

METHODS

process()

Generated the PDF as epr parameters in $c->stash->{wkhtmltopdf} or other configured stash key. Calls render() to perform actual rendering. Output is stored in $c-response->body>.

It is possible to forward to the process method of the view from inside Catalyst:

$c->forward('View::Wkhtmltopdf');

However, this is usually done automatically by Catalyst::Action::RenderView.

render($c, \%args)

Generates a PDF from the arguments in \%args and returns it. Arguments are the same one would place in the stash key for rendering + output via process(), but the following are (of course) ignored: disposition, filename (as they only apply when outputting the content to the client).

You can pass a template_args key inside the arguments hashref, which will be passed to Catalyst::View::TT's render() method. If not supplied, undef will be passed, so the TT view method will behave as per its documentation.

CHARACTER ENCODING

At present time this library just uses UTF-8, which means it should work in most circumstances. Patches are welcome for support of different character sets.

REQUIREMENTS

wkhtmltopdf command should be available on your system.

TODO

More configuration options (all the ones which wkhtmltopdf supports, likely) should be added. Also, we'll wanto to allow to override them all at runtime.

We might want to use pipes (IPC::Open2) instead of relying on temp files.

And yes... we need to write tests!

CONTRIBUTE

Project in on GitHub:

https://github.com/lordarthas/Catalyst-View-Wkhtmltopdf

AUTHOR

Michele Beltrame <arthas@cpan.org>

CONTRIBUTORS

jegade

LICENSE

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

SEE ALSO

Catalyst, Catalyst::View::TT

http://code.google.com/p/wkhtmltopdf/