The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

NAME

PDF::WebKit - Use WebKit to Generate PDFs from HTML (via wkhtmltopdf)

SYNOPSIS

use PDF::WebKit;

# PDF::WebKit->new takes the HTML and any options for wkhtmltopdf
# run `wkhtmltopdf --extended-help` for a full list of options
my $kit = PDF::WebKit->new(\$html, page_size => 'Letter');
push @{ $kit->stylesheets }, "/path/to/css/file";

# Get an inline PDF
my $pdf = $kit->to_pdf;

# save the PDF to a file
my $file = $kit->to_file('/path/to/save/pdf');

# PDF::WebKit can optionally accept a URL or a File
# Stylesheets cannot be added when source is provided as a URL or File.
my $kit = PDF::WebKit->new('http://google.com');
my $kit = PDF::WebKit->new('/path/to/html');

# Add any kind of option through meta tags
my $kit = PDF::WebKit->new(\'<html><head><meta name="pdfkit-page_size" content="Letter"...');

DESCRIPTION

PDF::WebKit uses wkhtmltopdf to convert HTML documents into PDFs. It is a port of the elegant PDFKit Ruby library.

wkhtmltopdf generates beautiful PDFs by leveraging the rendering power of Qt's WebKit browser engine (used by both Apple Safari and Google Chrome browsers).

Configuration

Configuration of PDF::WebKit is configured globally by calling the PDF::WebKit->configure class method:

PDF::WebKit->configure(sub {
  # default `which wkhtmltopdf`
  $_->wkhtmltopdf('/path/to/wkhtmltopdf');

  # default 'pdf-webkit-'
  $_->meta_tag_prefix('my-prefix-');

  $_->default_options->{'--orientation'} = 'Portrait';
});

See the new method for the standard default options.

Constructor

new($SOURCE_URL,%OPTIONS)
new($SOURCE_FILENAME,%OPTIONS)
new(\$SOURCE_HTML,%OPTIONS)

Creates and returns a new instance. If the first parameter looks like a URL, it is treated as a URL and handed off to wkhtmltopdf verbatim. If it is is a reference to a scalar, it is an HTML document body. Otherwise, the parameter is interpreted as a filename.

The %OPTIONS hash is a list of name/value pairs for command-line options to wkhtmltopdf. These options can augment or override the default options. For options with no associated value, pass "YES" (case insensitive) as the value, e.g. grayscale => "YES".

The default options are:

--page-size     Letter
--margin-top    0.75in
--margin_right  0.75in
--margin_bottom 0.75in
--margin_left   0.75in
--encoding      UTF-8

Methods

command

Returns the list of command-line arguments that would be used to execute wkhtmltopdf.

to_pdf

Processes the source material and returns a PDF as a string.

to_file($PATH)

Processes the source material and creates a PDF at $PATH. Returns a filehandle opened on $PATH.

SEE ALSO

PDFKit, wkhtmltopdf, WKHTMLTOPDF (a lower-level wrapper for wkhtmltopdf).

AUTHOR

Philip Garrett <philip.garrett@icainformatics.com>

CONTRIBUTORS

Christian Walde <walde.christian@gmail.com>

CONTRIBUTING

If you'd like to contribute, just fork my repository on Github, commit your changes and send me a pull request.

http://github.com/kingpong/perl-PDF-WebKit

ACKNOWLEDGMENTS

This code is nearly a line-by-line port of Jared Pace's PDFKit. https://github.com/jdpace/PDFKit

COPYRIGHT & LICENSE

Copyright (c) 2011 by Informatics Corporation of America.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.