EXT: exinit | wkhtmltopdf¶

What does it do?¶

exinit_wkhtmltopdf generates PDF files from the HTML output of TYPO3 frontend pages and triggers their download. The rendering is done by an application called wkhtmltopdf which is shipped with the extension in form of an executable for Linux. Wkhtmltopdf uses the WebKit browser engine and therefore creates PDF files which look quite the same way they would look in webbrowsers using the same engine – for example Apple Safari or Google Chrome.

Screenshots¶

Safari showing typo3.org

A PDF generated by wkhtmltopdf showing typo3.org

Rendering comparison of Apple Safari and wkhtmltopdf. As you can see it looks quite the same. Wkhtmltopdf even executes javascript. This for example enables to you to use Cufón for font rendering in the PDF version.

How to trigger the PDF generation¶

PDF file generation is triggered by the type parameter. The default page type number to operate on is 4096. Therefore you can render pdf files by appending &type=4096 to a pages URL. For example: index.php?id=1&type=4096

The page type number can be changed by TypoScript. You may want to take a look at the next chapter if you want to do so.

Caching¶

Generated PDF files are cached (saved on the hard disk) to take load of the server. They are deleted automatically as soon as you clear the TYPO3 cache in the backend.

Requirements¶

• exinit_wkhtmltopdf requires at least TYPO3 4.3.0.
• If you intend using the 32bit wkhtmltopdf binary shipped with this extension but your server is running a 64bit Linux Kernel you need to ensure that it includes IA-32 support and you have installed IA-32 runtime libraries. If you are hosting your TYPO3 project on a managed server or webspace package this will probably be the case. Alternatively you can download the AMD64 port of wkhtmltopdf.
• If your server isn't running Linux you need to download a version of wkhtmltopdf suitable for your operating system.

An AMD64 port for Linux and executables for several different operating systems can be found on the projects website: http://code.google.com/p/wkhtmltopdf/ .

Installation¶

• Download and install the extension via the extension manager. Change the extension configuration to your needs. Make sure you at least change the “sharedSecret” which is used to identify requests by wkhtmltopdf. If you don't change this value, users will be able to view the HTML source used for PDF file generation by requesting a page and adding the default shared secret to the URL.
• Add the extensions' default TypoScript: Edit your root template, choose the “Includes” tab and add the extensions default TypoScript configuration by clicking on “wkhtmltopdf (exinit_wkhtmltopdf)”. Save the template record.
• Customize the extensions' TypoScript setup. If you don't intend to use the wkhtmltopdf binary shipped with this extension you'll probably will want to change the path to the binary here. If you're not using TemplaVoilà you may want to change the path to the template file to be used. In any case you will probably want to configure the CSS files to be used.
• Test if anything works as expected. For example you could open http://example.com/?type=4096 in your browser to generate a PDF file from your start page.

Reference¶

plugin.tx_exinitwkhtmltopdf {
    ignoreTemplaVoilaInstallation = 0
    wkhtmltopdf {
            options {
                    margin-left = 15mm
                    margin-right = 15mm
                    margin-top = 15mm
                    margin-bottom = 15mm
            }
    }
}

plugin.tx_exinitwkhtmltopdf {
    filePrefix = ewhtp_
    wkhtmltopdf {
            executablePath = EXT:exinit_wkhtmltopdf/bin/wkhtmltopdf-i386
            options {
                    footer-right = Footer
                    footer-right.stdWrap.warp = | Message
                    stop-slow-scripts =
            }
    }
}

lib.tx_exinitwkhtmltopdf_template = TEMPLATE
lib.tx_exinitwkhtmltopdf_template {
    template = FILE
    template.file = EXT:exinit_wkhtmltopdf/res/template.html
    workOnSubpart = DOCUMENT
    marks.main_content_area < styles.content.get
}

How it works¶

exinit_wkhtmltopdf can be seen as a gateway for wkhtmltopdf. The extension adds a new page object to the TypoScript setup and – once a page is requested with the corresponding page type - causes TYPO3 to use a custom page generator script instead of the default one provided by the cms package. The custom page generator queries the cache and – if the requested PDF file has been found in the cache – triggers the download. If the file hasn't been generated yet, the custom page generator executes wkhtmltopdf which renders and saves the PDF file which then gets added to the cache.

Security¶

The usage of exinit_wkhtmltopdf is quite restricted. Users can only access TYPO3 frontend pages by using it. It isn't possible to render any files on the webserver which aren't embedded in or referenced by the rendered HTML code of a frontend page. Extensions that work by passing the URLs to render as get or post parameters may pass over security restrictions. For example if you are identifying developers by the loopback IP-Address (127.0.0.1 / localhost), requests made by an external tool like wkhtmltopdf will be treated as being made from developers. In some cases you could thereby could give data to normal frontend users which isn't meant for them to be seen. Another scenario is the usage of Apaches' mod_info. Usually access to this module is limited to the loopback IP-Address. If a user somehow figures out the location that triggers the module to output content (for example /server-info) he could access it and get sensitive information like system paths by using a PDF generator that takes the URLs to render from get or post parameters.

0.1.0¶