.. You may want to use the usual include line. Uncomment and adjust the path. .. include:: ../Includes.txt =============== EXT: Webkit PDF =============== :Author: Kasper Skårhøj :Created: 2002-11-01T00:32:00 :Changed by: Reinhard Führicht :Changed: 2012-02-26T13:06:42.890000000 :Classification: webkitpdf :Author: Dev-Team Typoheads :Email: dev@typoheads.at :Info 4: :Language: en |img-1| |img-2| EXT: Webkit PDF - webkitpdf .. _EXT-Webkit-PDF: EXT: Webkit PDF =============== Extension Key: webkitpdf Language: en Copyright 2009, Dev-Team Typoheads, This document is published under the Open Content License available from http://www.opencontent.org/opl.shtml The content of this document is related to TYPO3 \- a GNU/GPL CMS/Framework available from www.typo3.org .. _Table-of-Contents: Table of Contents ----------------- `EXT: Webkit PDF 1 <#__RefHeading__1108_1832455999>`_ **`Introduction 3 <#__RefHeading__1110_1832455999>`_** `What does it do? 3 <#__RefHeading__6112_930307826>`_ `IMPORTANT NOTICES 3 <#__RefHeading__1114_1832455999>`_ **`Administration 4 <#__RefHeading__1118_1832455999>`_** **`Configuration 5 <#__RefHeading__1120_1832455999>`_** `Reference 5 <#__RefHeading__1122_1832455999>`_ `General Options 5 <#__RefHeading__1124_1832455999>`_ `Script parameters 6 <#__RefHeading__1126_1832455999>`_ **`Troubleshooting 7 <#__RefHeading__676_152754715>`_** `Upgrading from version 1.1.3 (or below) to any later version 7 <#__RefHeading__678_152754715>`_ `Generating PDFs of access protected pages 7 <#__RefHeading__680_152754715>`_ `Warnings on PDF generation page 7 <#__RefHeading__690_152754715>`_ `Use a page type to render PDFs 8 <#__RefHeading__3571_930307826>`_ **`Known problems 9 <#__RefHeading__1130_1832455999>`_** **`To-Do list 10 <#__RefHeading__1132_1832455999>`_** **`ChangeLog 11 <#__RefHeading__1134_1832455999>`_** .. _Introduction: Introduction ------------ .. _What-does-it-do: What does it do? ^^^^^^^^^^^^^^^^ WebkitPDF uses the binary “wkhtmtopdf” (http://code.google.com/p/wkhtmltopdf/) to render given pages to a PDF file on the fly. The binary for 32bit i386 unix systems is shipped with the extension. Once rendered, the PDF files are cached in the filesystem for a better performance. The caching information is kept in a database table. Clearing the cache in the TYPO3 backend will remove those PDF files which exceed a certain lifetime limit. This limit can be set in the configuration section of the extension manager. .. _IMPORTANT-NOTICES: IMPORTANT NOTICES """"""""""""""""" - A binary script (res/wkhtmltopdf) is included to perform this task. The user must have the right permissions to execute this binary (script has to be executable). You can move it to another location and specify the new path via TypoScript. - This extension does NOT work on Windows systems! - The binary provided by this extension does only work on 32bit systems. To run this extension on a 64bit system, download the binary provided on forge.typo3.org/issues/show/4337 and use the TypoScript setting customScriptPath to point to the downloaded binary. - The binary script apparently has some dependencies. Make sure you have libfreetype installed. It may occur that libfreetype alone isn't enough. In this case we recommend to install GLIBC > 2.4. - If you experience problems (e.g. the PDF is not readable), try to run the script manually from a shell environment. To get the exact call which was made by WebkitPDF, use the debugScriptCall setting in TypoScript. .. _Administration: Administration -------------- - Install via extension manager. - Create a new page and add a plugin 'Webkit PDF'. - Go to your TypoScript template and include the static template from extension 'WebKit PDF' in your template. - Go to template constant editor. Set pluginPid according to the page id with the plugin (of step 2). The text of the link can be changed in linkText. - Integrate the link for PDF generation in your page using the below TypoScript example. - Pass the page IDs to render in GET-parameter 'urls' (or custom if specified via TS) - Parameter is an array of URLs Example: :: page.70 < plugin.tx_webkitpdf_pi1.pdfLink See the configuration section of plugin.tx\_webkitpdf\_pi1.pdfLink for more details on how the link is generated. .. _Configuration: Configuration ------------- .. _Reference: Reference ^^^^^^^^^ .. _General-Options: General Options """"""""""""""" .. ### BEGIN~OF~TABLE ### .. _allowedHosts: allowedHosts ~~~~~~~~~~~~ .. container:: table-row Property allowedHosts Data type String Description Comma separated list of allowed hosts for PDF generation. WebkitPDF only allows the current host per default. Default .. _filePrefix: filePrefix ~~~~~~~~~~ .. container:: table-row Property filePrefix Data type String/stdWrap Description Custom prefix for the name of the generated PDF file Default .. _customScriptPath: customScriptPath ~~~~~~~~~~~~~~~~ .. container:: table-row Property customScriptPath Data type String /stdWrap Description If you copy the used shell script to another location for permission reasons, you can enter the new path to the executable. Default .. _customTempOutputPath: customTempOutputPath ~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property customTempOutputPath Data type String/stdWrap Description Custom path to store the temp files Default typo3temp .. _copyrightNotice: copyrightNotice ~~~~~~~~~~~~~~~ .. container:: table-row Property copyrightNotice Data type String/stdWrap Description Enter a name of a person or organisation to be shown as a copyright notice. Copyright 2010 [name] Default .. _additionalStylesheet: additionalStylesheet ~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property additionalStylesheet Data type String/stdWrap Description Enter path to an additional CSS file. Default .. _customParameterName: customParameterName ~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property customParameterName Data type String/stdWrap Description Custom name of the GET parameter containing the page IDs Default selected\_pages .. _pageURLInHeader: pageURLInHeader ~~~~~~~~~~~~~~~ .. container:: table-row Property pageURLInHeader Data type Boolean (1/0)/stdWrap Description Add the URL of the page to PDF header Default 0 .. _debugScriptCall: debugScriptCall ~~~~~~~~~~~~~~~ .. container:: table-row Property debugScriptCall Data type Boolean (1/0)/stdWrap Description Prints the call of the script to the screen for debugging purposes. You can copy/paste this call into the shell to see if the call itself throws errors. Default 0 .. _staticFileName: staticFileName ~~~~~~~~~~~~~~ .. container:: table-row Property staticFileName Data type String/stdWrap Description Enter a filename for the downloadable PDF. You can use stdWrap to add dynamic things like timestamp to the filename. If you leave this option empty, the filename will be the same as the name of the temporary file. Default .. _openFilesInline: openFilesInline ~~~~~~~~~~~~~~~ .. container:: table-row Property openFilesInline Data type Boolean (1/0)/stdWrap Description Normally, the PDF files are sent with a “Content-Disposition” header “attachment” which causes the browser to show a “Save or open” dialog. If “openFilesInline” is set to “1”, the PDF files are opened inline in the browser. If the browser doesn't know how to show a PDF file inline, the download dialog is shown. Default 0 .. _disableCache: disableCache ~~~~~~~~~~~~ .. container:: table-row Property disableCache Data type Boolean (1/0)/stdWrap Description Overrides the settings made in extension manager. Use this to disable the cache based on certain conditions. If “disableCache” is set to “1”, no files are stored in typo3temp/tx\_webkitpdf Default 0 .. _scriptParams: scriptParams ~~~~~~~~~~~~ .. container:: table-row Property scriptParams Data type Array Every setting inside: String/stdWrap Description Enter parameters for the script call directly. See section “ `Script parameters <#1.4.1.2.Script%20parameters|outline>`_ ” for a full list. Enter parameters this way: scriptParams { margin-left = 35mm footer-line = } The script execution will look this way: wkhtmltopdf --margin-left 35mm --footer-line ... Default .. _pdfLink: pdfLink ~~~~~~~ .. container:: table-row Property pdfLink Data type cObj Description Pre-built cObject to link to PDF generation. pdfLink is a helper object to make the link generation as easy as possible. It's use is optional, you can create the link however you like. It uses the following TypoScript: **setup.txt:** :: plugin.tx_webkitpdf_pi1.pdfLink = TEXT plugin.tx_webkitpdf_pi1.pdfLink { value = {$plugin.tx_webkitpdf_pi1.pdfLink.linkText} typolink { parameter = {$plugin.tx_webkitpdf_pi1.pdfLink.pluginPid} no_cache = {$plugin.tx_webkitpdf_pi1.pdfLink.no_cache} additionalParams { data = getIndpEnv:TYPO3_REQUEST_URL wrap = &tx_webkitpdf_pi1[urls][0]=| } } } **constants.txt:** :: plugin.tx_webkitpdf_pi1.pdfLink { pluginPid = 123 linkText = Save as PDF no_cache = 1 } The HTML result is: :: Save as PDF You simply have to use plugin.tx\_webkitpdf\_pi1.pdfLink in your page template. The pages which should be rendered as PDF have to be set as URL in tx\_webkitpdf\_pi1[urls][]. If you like to have one page rendered, use: &tx\_webkitpdf\_pi1[urls][0]=URL If you like to have multiple pages rendered in one PDF file, just add more parameters: &tx\_webkitpdf\_pi1[urls][1]=URL&tx\_webkitpdf\_pi1[urls][2]=URL and so on. Since cObject TEXT with typolink is used here, you have stdWrap which opens up infinite ways to realize your favorite link. Default cObj TEXT with typolink (see description) .. ###### END~OF~TABLE ###### [plugin.tx\_webkitpdf\_pi1] .. _Script-parameters: Script parameters """"""""""""""""" A list of available parameters can be found here: http://madalgo.au.dk/~jakobt/wkhtmltopdf-0.10.0\_beta2-doc.html When using this in TypoScript omit the '--'. Note: The following parameters will override some TypoScript settings: .. ### BEGIN~OF~TABLE ### .. _user-style-sheet: user-style-sheet ~~~~~~~~~~~~~~~~ .. container:: table-row Parameter user-style-sheet Overwrites this TypoScript setting additionalStylesheet .. _footer-left: footer-left ~~~~~~~~~~~ .. container:: table-row Parameter footer-left Overwrites this TypoScript setting copyrightNotice .. _header-center: header-center ~~~~~~~~~~~~~ .. container:: table-row Parameter header-center Overwrites this TypoScript setting pageURLInHeader .. ###### END~OF~TABLE ###### .. _Troubleshooting: Troubleshooting --------------- .. _Upgrading-from-version-1-1-3-or-below-to-any-later-version: Upgrading from version 1.1.3 (or below) to any later version ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ **Link generation has changed in versions >1.1.3 ! You need to perform some manual steps to update your environment.** The userfunc is not needed anymore and its use is deprecated. Instead, you have to use a built-in TypoScript object plugin.tx\_webkitpdf\_pi1.pdfLink **Follow these steps after upgrading from 1.1.3 (or below) to any later version:** The old userfunc TypoScript which is going to be replaced should look like this: :: includeLibs.webkit = EXT:webkitpdf/res/user_webkitpdf.php lib.pdf = USER lib.pdf.userFunc = user_webkitpdf->user_getPDFLink lib.pdf { pid = 23 linkText = Save as PDF } - First, go to your TypoScript template and include the static template from extension 'WebKit PDF' in your template. - Go to template constant editor. Set pluginPid according to lib.pdf.pid (it's the page id which contains the plugin 'WebKit PDF'). The text of the link can be set in linkText. - Remove the old TypoScript as shown above and replace it by the below line: :: lib.pdf < plugin.tx_webkitpdf_pi1.pdfLink .. _Generating-PDFs-of-access-protected-pages: Generating PDFs of access protected pages ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ WebkitPDF is capable of generating PDFs of access protected pages. But in order to be able to do so, you have to do some configuration in the install tool: - Set [FE][lockIP] = 0 - Set [FE][lockHashKeyWords] = This way the binary used by WebkitPDF is able to access the page to render from “outside”. .. _Warnings-on-PDF-generation-page: Warnings on PDF generation page ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ While generating a PDF sometimes PHP warnings are logged in the webserver's error log. This depends on your TYPO3 and server configuration. PHP Warning: Cannot modify header information - headers already sent by (output started at /path/to/typo3/typo3conf/ext/webkitpdf/pi1/class .tx\_webkitpdf\_pi1.php:160) in /path/to/typo3/typo3/sysext/cms/tslib/class.tslib\_fe.php on line 3229, referer: … To fix this, add this TS to the page with the WebKit PDF-plugin: :: config { disableCharsetHeader = 1 sendCacheHeaders = 0 additionalHeaders = } .. _Use-a-page-type-to-render-PDFs: Use a page type to render PDFs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ You can use WebkitPDF on a special page type to show a PDF. :: PDF = PAGE PDF.typeNum = 250 PDF.config { disableAllHeaderCode = 1 disableCharsetHeader = 1 disablePrefixComment = 1 } PDF.10 < plugin.tx_webkitpdf_pi1 PDF.10 { customScriptPath = /usr/bin/ urls { typolink.parameter.data = TSFE:id typolink.returnLast = url dataWrap = {getIndpEnv:TYPO3_REQUEST_HOST}/| } staticFileName.data = page:title staticFileName.wrap = |.pdf } This way, all calls to &type=250 result in a PDF.Now you can put a link to all your pages: :: page.1 = TEXT page.1 { typolink { parameter.data = TSFE:id additionalParams = &type=250 } } .. _Known-problems: Known problems -------------- None currently .. _To-Do-list: To-Do list ---------- Waiting for Flash support. This would be really awesome! .. _ChangeLog: ChangeLog --------- - 1.0.0: initial release. - 1.0.1: - Fixed usage with multiple GET parameters - Added userFunc to generate PDF link - New TS option: pageURLInHeader - Parameter linkText for userFunc can be any TS object now - 1.1.0 - Extension caches the rendered PDF files for reuse. Clear cache in backend. - Caching is done in a DB table. Clearing the cache clears temporary files older than 10 minutes. - 1.1.1 Set any available script parameter via TypoScript. This gives you full flexibility. - 1.1.2 TypoScript-Option to let WebkitPDF return only the name of the generated file. - 1.1.3 - Removed unnecessary code from ext\_tables.php - Fixed issue with the PDF download occurring in some browsers - 1.1.4 Security fix - 1.1.5 - Fixed caching - Cache files only if cache threshold is > 0 - Every TS option (except scriptParams) has stdWrap now - Moved some methods to a new utils class - 1.1.6 - Updated binary to version 1.0.0beta2 - Removed parts from documentation and referred to public manual of the binary instead - “scriptParams“ have stdWrap too now 11 .. ######CUTTER_MARK_IMAGES###### .. |img-1| image:: img-1.png .. :align: left .. |img-2| image:: img-2.png .. :border: 0 .. :height: 21 .. :hspace: 9 .. :id: Grafik2 .. :name: Grafik2 .. :width: 87