DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:dw2pdf

This is an old revision of the document!


DW2PDF Plugin

Compatible with DokuWiki

2016-06-26, Weatherwax, Binky, Ponder Stibbons, Hrun,Detritus, Frusterick Manners

plugin Export DokuWiki content to PDF

Last updated on
2017-11-15
Provides
Action, Render
Repository
Source
Conflicts with
inlineeditor, subjectindex

This extension has not been updated in over 2 years. It may no longer be maintained or supported and may have compatibility issues.

Similar to bookcreator, ebookexport, html2pdf, pdfex, xslfo

Tagged with export, pdf

Needed for bookcreator, pdftools

Previous developer: Luigi Micco

Download and Installation

Download and install the plugin using the bundled Extension Manager using the URL given above. Refer to Plugins on how to install plugins manually.

:!: The plugin can't be installed through the plugin manager on pre-Angua releases, because it's too big and the plugin manager will fail while downloading. Please install it manually and make sure the installed directory is named dw2pdf.

Only PHP 5.6 and newer are supported by dw2pdf plugin.

To export images with an alpha channel (used for transparency), you need to install the GD library for PHP. For example on Debian systems:

sudo apt-get install php5-gd

Also see the PHP with gd tips page.

Recent Changes

Overview

The goal of this plugin was to provide a simple, ready-to-go PDF converter that almost faithfully replicates the screen view of your wiki pages (i.e. doesn't convert them to a print-document format like the latex plugin). It also bundles the necessary fonts and libraries (hence the 48MB size) so that you should not need to do any configuration to get it up and running as quickly as possible.

Features

  • Uses the mPDF PHP library.
  • Handles different languages (it bundles the large, but relatively complete Unicode font).
  • Easy customizing through headers, footers and CSS
  • Automatic index of bookmarks
  • Use with the BookCreator plugin to create a PDF from only the pages selected.

Since July 2017 version 7.0-beta of mPDF library is included, which supports PHP7, but not PHP 5.4 and older.

As (temporary) fallback the following old releases could be found:

  • Since 11 June 2015 version 6.0 of the mPDF library was included. This should significantly improve the styling possibilities. However there could also be regressions.
    Release based at previous mPDF 6.0 version – dw2pdf Plugin with mPDF 6.0.0.zip (50 MB)
  • Release based at previous mPDF 5.7.4 version – dw2pdf Plugin with mPDF 5.7.4.zip (12 MB)

Installation

To use the plugin, you simply need to call the page passing it a “do=export_pdf” PHP argument for a single page. Some templates let the plugin extend the pagetools automatically. For other templates you need to implement this yourself to add a button or similar somewhere in your template design.

See the syntax section on how to export an entire namespace as one PDF.

Export button in pagetools/menu's

Since 2013-12-08 Binky release this plugin automatically adds the export button to the page tools of the DokuWiki template. When required, you can disable it via the Configuration Manager.

For more details about how to implement it in your template, see pagetool.

Syntax

To create a link in any wiki page to export any namespace, you can use the following syntax: ~~PDFNS>namespace|pdftitle~~

  • namespace is the namespace you want to export
  • pdftitle is the title of the generated output PDF
  • You can add further options (like &book_order=pagename) by simply appending them to the pdftitle.

Handling of startpages: If the page <namespace>:start doesn't exist, it checks if the page with the name <namespace> exists and will add to the pdf as well.

Configuration

The plugin provides a few configuration settings that can be configured in the Configuration Manager. Some can be overridden via url-parameters.

  • Only via url-parameters:

Document Title

do=export_pdf – Export current wiki page

  • book_title=<urlencode%20title>
    Optional, default using the title of the wiki article.

do=export_pdfns – Export the requested namespace

  • book_ns=<namespace> Exported namespace
  • book_title=<urlencode%20title>
  • book_nsdepth=<number> (optional) – Down to which level the pages are collected for inclusion (default: all levels included)
  • book_order=<order> (optional) – Sort included pages by natural(default), date or pagename

Parameter selection is posted with a page list – Export pdf book via Bookcreator Plugin

  • book_title=<urlencode%20title>
  • Override-able via url-parameters:

If a url-parameter is provided, that value is used, otherwise the plugin config setting from the Configuration Manager is used.

Pagesize

pagesize=A4|letter|etc
A page format as supported by mPDF. Usually A4 or letter. See the docs for other allowed values for the format parameter of mpdf(). mpdf.github.io

Orientation

orientation=portrait|landscape
Page orientation of the whole document, you can select Portrait or Landscape.

Also you can change the orientation of only some pages. Adding the syntax will change the orientation, until you change it with the other orientation syntax.

~~PDF:LANDSCAPE~~
~~PDF:PORTRAIT~~

Double-sided document

doublesided=0|1
By default a double-sided PDF document is outputted. The first page is an odd page (left hand-side page) and further even-odd page pairs are added. Disabling this will output a single-sided document with only odd pages. The single-sided document doesn't add additional blank pages if a Table of Contents or cover page is included (and you can still send it to the printer as double-sided, but it won't have odd-even formatting).

Table of Contents

toc=0|1
toclevels=<top>-<max>
An auto-generated Table of Contents can be included by enabling the setting 'toc' (values: 0 or 1). By default, the same headings are added to the PDF Table of Contents as in the TOC for a wiki article (as set with toptoclevel and maxtoclevel). The range of headings can be overridden by setting 'toclevels' e.g. 1-3. Where the values correspond to <toptoclevel>-<maxtoclevel>.

Bookmarks

maxbookmarks=0|1|2|3|4|5
By default the plugin generates PDF bookmarks for each headline in the source page. You can lower the number here to include only higher level headlines in the bookmarks. Set it 0 to disable bookmarks all together.

Template

tpl=<foldername>
Choose which PDF template (see below) should be used by default. The template can be overridden with the tpl request variable e.g. add &tpl=yourtemplate to the export url.

  • Only via configuration manager:

Output Control

The output option controls if PDF should be opened within the Browser (when a PDF plugin is installed and the browser is configured correctly) or should always be downloaded.

Caching

By default, generated PDFs are cached. This includes embedded images. This means the ACLs for embedded images will not be rechecked when a user requests a cached PDF. If this is a problem, you should disable caching.

Plugin Styles

The plugin automatically uses print.css and pdf.css files of installed 3rd party plugins to style plugin content. Often plugins do not provide such styles or you may actually prefer their screen styles. In that case list the names of these plugins here.

QR code

Via a placeholder a QR code can be added in the pdf-templates, which is generated with the size given in the configuration. The plugin uses an online generator. Setting the size to zero will disable this feature.

Show export button

Lets you show or hide the toolbar button in the pagetools.

Plugin Compatibility

To work with other plugins you have to add dw2pdf to its action_plugin_include supportedModes member variable

var $supportedModes = array('xhtml', 'metadata','dw2pdf'); 

Otherwise you may have problems with caching.

PDF Templates

PDF Templates define the design of the created PDF files and are a good way to easily customize them to your Corporate Identity. The default PDF template which is shipped with this plugin is shown on the right. It has simple headers, footers and citation box.

To create a new template, just create a new folder within the plugin's lib/plugins/dw2pdf/tpl/ folder and put your header, footers, cover page, and style definitions in it. See lib/plugins/dw2pdf/tpl/default for an example. Don't modify the template default, these template can be overwritten on updates, so you will lose your changes.

Headers and Footers

The following files can be created and will be used to set headers and footers on odd or even pages. Special headers/footers can be used on the first page of a document. If a file does not exist the next more generic one will be tried. Eg. if you don't differ between even and odd pages, just the header.html is used.

  • header.html – Header for all pages
  • header_odd.html – Header for odd pages
  • header_even.html – Header for even pages
  • header_first.html – Header for the first page
  • footer.html – Footer for all pages
  • footer_odd.html – Footer for odd pages
  • footer_even.html – Footer for even pages
  • footer_first.html – Footer for the first page
  • citation.html – Citationbox to be printed after each article
  • cover.html – If exists, added once before first page
  • back.html – If exists, added once after last page

You can use all HTML that is understood by mPDF (See http://mpdf1.com/manual/index.php?tid=256 ormpdf.github.io)

If you reference image files from your pdf-template file, be sure to prefix them with the @TPLBASE@ (or for some cases @TPLINC@) parameter (See Replacements below).

Replacements

The following replacement patterns can be used within the header and footer files.

  • @PAGE@ – current page number in the PDF
  • @PAGES@ – number of all pages in the PDF (excluded a ToC)
  • @TITLE@ – the article's title
  • @WIKI@ – the wiki's title
  • @WIKIURL@URL to the wiki
  • @DATE@ – time when the PDF was created (might be in the past if cached)
  • @BASE@ – the wiki base directory
  • @TPLBASE@ – the URL base of PDF-template directory (use to reference images) (e.g. /[wikiURLbase]/lib/plugins/dw2pdf/tpl/<yourtplfolder>/ )
  • @TPLINC@ – the absolute path to the PDF template directory on the filesystem (e.g. /var/www/dokuwiki/lib/plugins/dw2pdf/tpl/<yourtplfolder>/)
  • @INC@ – the absolute wiki install directory on the filesystem
  • @DATE(<date>[, <format>])@ – formats the given date with dformat or with the given format such as %Y-%m-%e, e.g. this would give just the current year @DATE(@DATE@,%Y)@

Remark about Bookcreator: The next page dependent replacements are only for citation.html updated for every page. In the headers and footers the ID of the bookmanager page of the Bookcreator is applied.

  • @ID@ – The article's pageID
  • @PAGEURL@URL to the article
  • @UPDATE@ – Time of the last update of the article
  • @QRCODE@ – QR code image pointing to the original page url (requires an online generator, see config setting)

Styles

Custom stylings can be provided in the following file of your pdf-template folder:

  • [wikibase]/lib/plugins/dw2pdf/tpl/<yourpdftplfolder>/style.css

You can use all the CSS that is understood by mPDF
(See https://mpdf.github.io/css-stylesheets/supported-css.html)

For developers

If you're a plugin developer and want to make your syntax plugin compatible with the PDF export, here are a few tips:

  • provide a useful print.css and PDF export will probably work out of the box
  • if you want to use special stylings for PDF export provide a pdf.css
  • your HTML and CSS should be simple enough to be understood by mpdf (see mpdf.github.io documentation)

If you want to provide custom HTML for the PDF export you should check if the renderer is a renderer_plugin_dw2pdf when rendering xhtml.

function render($mode, $renderer, $data){
    if($mode == 'xhtml') {
       if(is_a($renderer,'renderer_plugin_dw2pdf')){
           // this is the PDF export, render simple HTML here
       }else{
           // this is normal XHTML for Browsers, be fancy here
       }
       return true;
    }
    return false;
}

By default, dw2pdf will fetch embedded images via HTTP. If you want to embed local image files without going through HTTP, you can give their location by writing an img tag using the dw2pdf: pseudo protocol: <code php> $R→doc .= '<img src=“dw2pdf:/full/path/to/some/image.png”>'; </code> Examples: visrep Plugin (code), mathpublish plugin (code) ===== Issues and Requests ===== Please report issues and requests in the issue tracker: https://github.com/splitbrain/dokuwiki-plugin-dw2pdf/issues/ ==== How to collect more debug info? ==== If you are using the dw2pdf plugin and you don't get the wanted output, than you might investigate the data during its workflow. The dw2pdf plugin uses the HTML code of the print version of an wiki article (which has a leaner styling than the screen version) and converts this code with the mPDF-library to a pdf-file. Some options to investigate with the intermediate results are: - Look at the print preview of an article via the print preview function of your browser - Output the plain html for manually testing or reading. How-to output the plain html (just before it is fed into the mPDF library): - Enable the debugging mode of the wiki with the allowdebug setting (see also debugging) - Add url-parameter to the url used to initiate your pdf-export (copy and modify the link of the button or url you use): * Adding &debughtml=text displays html as plain text in the browser * Adding &debughtml=html displays html rendered by the browser See for the debugging options of the mPDF library related to images: images documentation of mPDF. ===== Sites using this plugin ===== Feel free to add yours here: * Practico Framework * Gain250 * AG Eulen (german) * BLËSK User Guide (English) * Handbuch HiOrg-Server (german) * PKUinfo: Informazioni, domande e risposte sulla fenilchetonuria * davidak wiki (german) * CD-HIT Wiki * FR-HIT Wiki * http://www.anngon-wiki.info (Vietnamese) * Versuch macht klug! Entdecke die Welt der Experimente mit A.Blümel * course on Multimedia Engineering at University of Alicante * Djangos DokuWiki Django * LaCie user manuals * AeroSeeD wiki * Wiki Kantuz * ESTechnical Documentation (English) * Prinz Eisenherz - Prince Valiant - Lexikon - Encyclopedia. * QEM srl manuals (italian) * LaRicetteria Recipes (italian) * financial accounting - webshop - interface (german) ===== Linked Images ===== Not all image format variations are successfully embedded in the PDF, even if they are properly displayed in DokuWiki. If you get missing images in your output, try stripping the Alpha channel of your (e.g. PNG) images. * The mPDF library used by this plugin for building the pdf requires the GD library for processing .png images with alpha channels. If using full http links, make sure the permissions are set up for retrieving the image directly (test in a browser). DokuWiki may prevent outside access to images in the data/media directory. ===== Password protection of generated documents ===== To set fixed password for generated documents, edit: dokuwiki/lib/plugins/dw2pdf/mpdf/config.php and add following lines: <code php> $this→setUserRights(); $this→SetProtection(array('print','copy', 'modify'),'password','password'); </code> where password is your password :) (filips) ===== iPhone/iPad ===== When using with an iPhone/iPad disable the setting: Seiten mit gzip komprimiert ausliefern otherwise this plugin will not generate PDF-Files on iPhone/iPad. ==== Discussion ==== === Linked Images === Is it possible to somehow add a tutorial for how to get external embedded images into the pdf? i'd really appreciate that. === Date format example === An example for the footer HTML placeholder / variable to show just the Year so that you can add a dated copyright notice : &copy; Your Company Name @DATE(@DATE@,%Y)@? === Disable Hyperlinks in export === >Is there a way to disable all hyperlinks in the pdf export? The pdf contains internal wiki links that the client can't access (as the wiki is for internal use only). The only way I have found is to modify the file mpdf.php: <code php lib/plugins/dw2pdf/mpdf/mpdf.php> /** * add this after line 8816 */ $annot=''; </code> === Additional config pages === Feature request : Can we have a footer_last.html and header_last.html for the back cover page or front cover page? === Styling and sizing the box that appears when hovering over the TOC in the pdf === I see a huge yellow box with a number in it when hovering over the TOC in the PDF. I'd like to make it smaller, and less yellow and put some useful information in it or turn it off but I've not found how to do this.

plugin/dw2pdf.1511101098.txt.gz · Last modified: 2017-11-19 15:18 by Klap-in

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki