Differences

This shows you the differences between two versions of the page.

--- plugin:dw2pdf [2017-11-12 23:50] – version upped andi
+++ plugin:dw2pdf [2023-11-25 23:50] (current) – version upped andi
@@ Line 6: / Line 6: @@
 email      : andi@splitbrain.org, klapinklapin@gmail.com
 type       : action, renderer
-lastupdate : 2017-11-12
+lastupdate : 2023-11-25
-compatible : 2016-06-26, Weatherwax, Binky, Ponder Stibbons, Hrun,Detritus, Frusterick Manners
+compatible : !Greebo, Hogfather, Igor, Jack Jackrum
 depends    :
 conflicts  :
@@ Line 22: / Line 22: @@
 ===== 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.
+Search and install the plugin using the [[plugin:extension|Extension Manager]]. 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 7.4 up to PHP 8.1** are supported by dw2pdf plugin. At rather short term support for PHP 7.4 will be dropped.
-Only **PHP 5.6 and newer** are supported by dw2pdf plugin.
+To export (png) images with an alpha channel (used for transparency), you need to install the GD library for PHP. For example on Debian systems:
-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 php-gd
-  sudo apt-get install php5-gd
 Also see the [[:tips:phpwithgd|PHP with gd]] tips page.
@@ Line 44: / Line 42: @@
 ===== Features =====
-  * Uses the [[http://www.mpdf1.com/|mPDF]] PHP library.
+  * Uses the [[https://mpdf.github.io|mPDF]] PHP library.
   * Handles different languages (it bundles the large, but relatively complete Unicode font).
   * Easy customizing through headers, footers and CSS
@@ Line 56: / Line 54: @@
   * Release based at previous mPDF 5.7.4 version -- [[https://github.com/splitbrain/dokuwiki-plugin-dw2pdf/archive/mpdf574.zip|dw2pdf Plugin with mPDF 5.7.4.zip]] (12 MB)
-===== Installation =====
+===== Usage =====
+There are three ways to export:
+  * **Export one page**\\ You simply need to call the page with an additional ''do=export_pdf'' URL parameter. This starts the PDF export of the page. Some templates let the plugin extend the [[plugin:dw2pdf:pagetools]] automatically. For other templates you need to implement this yourself to add a button or similar somewhere in your template design.
+  * **Export an entire namespace**\\ There is the URL parameter ''do=export_pdfns'' which let you export a chosen entire namespace as one PDF (e.g. use ''&do=export_pdfns&book_ns=my:namespace&book_title=Mytitle'' (See [[plugin:dw2pdf:configuration|Configuration options]] on how to exclude specific pages). Or create a link with the [[#Syntax|syntax]]).
+  * **Export selection of pages**\\ If you need to select just some pages to export to one PDF, you can use [[plugin:Bookcreator]] plugin, which offers an interface for the dw2pdf plugin.
-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.
+===== HowTo's=====
+Please refer to the following pages to learn how to use or support the plugin:
+  * Set [[plugin:dw2pdf:configuration|Configuration options]] via URL or via the Configuration Manager
+  * [[plugin:dw2pdf:pagetool|How to add export button in pagetools/menu's]]
+  * [[plugin:dw2pdf:pdftemplates|Layout and Customize the exported PDF for your (corporate) identity]]
+  * Plugin developers: [[plugin:dw2pdf:exportsupport|How to support export to PDF in your plugin]], including creating your own replacement patterns for use in HTML templates
-See the [[#Syntax|syntax]] section on how to export an entire namespace as one PDF.
-==== DokuWiki template ====
-{{:plugin:dw2pdf_pagetool_button_dokuwiki.png?150 |}}Since 2013-12-08 Binky release this plugin automatically adds the export button to the page tools. When required, you can disable it via the Configuration Manager.
-==== Default template ====
-Use the following to add another button in the upper or bottom button row of the default template((In ''/lib/tpl/default/main.php'', there are two divs that contain some buttons: ''%%<div class="bar" id="bar__top">%%'' and ''%%<div class="bar" id="bar__bottom">%%''. Just insert the HTML code inside one of the two divs (left or right) ))
-<code html>
-<form class="button" method="get" action="<?php wl($ID)?>">
-  <div class="no">
-    <input type="submit" value="Export to PDF" class="button" />
-    <input type="hidden" name="do" value="export_pdf" />
-    <input type="hidden" name="rev" value="<?php global $REV; echo $REV?>" />
-    <input type="hidden" name="id" value="<?php echo $ID?>" />
-  </div>
-</form>
-</code>
-Or use this for a simple 16x16 icon somewhere in your template:
-<code html>
-  <a href="<?php global $REV,$ID; echo exportlink($ID, 'pdf', "rev=$REV")?>">
-    <img src="<?php echo DOKU_BASE?>lib/images/fileicons/pdf.png" alt="PDF Export" />
-  </a>
-</code>
-You can mix the 2 previous methods, and get a button with an image inside, with this code:
-<code html>
-<form class="button" method="get" action="<?php wl($ID)?>">
-  <div class="no">
-    <button type="submit" class="button">
-      <img src="<?php echo DOKU_BASE?>lib/images/fileicons/pdf.png" alt="PDF Export" />
-      Export to PDF
-    </button>
-    <input type="hidden" name="do" value="export_pdf" />
-    <input type="hidden" name="rev" value="<?php global $REV; echo $REV?>" />
-    <input type="hidden" name="id" value="<?php echo $ID?>" />
-  </div>
-</form>
-</code>
-==== Monobook Template ====
-When using the template "[[template:monobook|monobook for DokuWiki]]", to have an Export PDF tab, in ''/user/tabs.php'', use this code
-<code php>
-//PDF plugin: export tab
-if (file_exists(DOKU_PLUGIN."dw2pdf/action.php") &&
-    !plugin_isdisabled("dw2pdf")){
-    $_monobook_tabs["tab-export-pdf"]["text"] = $lang["monobook_tab_exportpdf"];
-    $_monobook_tabs["tab-export-pdf"]["href"] = wl(getID(), array("do" => "export_pdf"), false, "&");
-}
-</code>
-Add translation to file ''/lib/tpl/monobook/lang/en/lang.php''
-<code php>
-$lang["monobook_tab_exportpdf"] = "Export as PDF";
-</code>
-==== Typo Template ====
-When using the [[template:typo]] template, add this code in ''lib/tpl/typo/tpl_functions.php'' just before ''%%print '  </ul>' . DOKU_LF;%%''
-<code php>
-print '<li>'.tpl_link(wl($ID,'do=export_pdf'), 'Export PDF', 'class="action export_pdf" rel="nofollow"',1).'</li>'.DOKU_LF
-</code>
-==== How-to auto-add export button in your template ====
-When your template has implemented the trigger for the [[devel:event:TEMPLATE_PAGETOOLS_DISPLAY]] event the dw2pdf plugin can extend your templates pagetools.
-In the ''addbutton()'' method of [[https://github.com/splitbrain/dokuwiki-plugin-dw2pdf/blob/master/action.php#L182|action.php]] a case should be added for the template, with the html of your button. Depending on the layout of your template, you might like to improve the ''style.css'' and the button images as well.
 ===== Syntax =====
@@ Line 148: / Line 79: @@
 Handling of [[config: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 [[plugin:config|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''
-Cookie ''list-pagelist'' is set 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 [[http://mpdf1.com/manual/index.php?tid=184|mpdf()]]. [[https://mpdf.github.io/|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 [[config:toptoclevel]] and [[config: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 =====
-Templates define the design of the created PDF files and are a good way to easily customize them to your Corporate Identity.
-To create a new template, just create a new folder within the plugin's ''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'' -- Added once before first page
-  * ''back.html'' -- Added once after last page
-You can use all HTML that is understood by mpdf (See http://mpdf1.com/manual/index.php?tid=256 or[[https://mpdf.github.io/|mpdf.github.io]])
-If you reference image files from your pdf-template file, be sure to prefix them with the @TPLBASE@ 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 PDF-template base directory (use to reference images) (e.g. ''[wikibase]/lib/plugins/dw2pdf/tpl/<yourtplfolder>/'' )
-  * ''@DATE(<date>[, <format>])@'' -- formats the given date with [[config:dformat]] or with the given format e.g. ''%Y-%m-%e''  eg: this would give just the current year ''@DATE(@DATE@,%Y)@''
-//Remark about Bookcreator//:
-The 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 [[https://mpdf.github.io/|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''.
-<code php>
-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;
-}
-</code>
-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>
 ===== Issues and Requests =====
-Please report issues and requests in the issue tracker: https://github.com/splitbrain/dokuwiki-plugin-dw2pdf/issues/
+Please report issues and requests in the issue tracker:\\ https://github.com/splitbrain/dokuwiki-plugin-dw2pdf/issues/
 ==== How to collect more debug info? ====
@@ Line 347: / Line 104: @@
 Feel free to add yours here:
-  * [[http://www.practico.org|Practico Framework]]
-  * [[http://wiki.gain250.com/wiki/doku.php?id=start:start|Gain250]]
-  * [[http://ageulen.de|AG Eulen (german)]]
   * [[http://www.blesk.ca/wiki/|BLËSK User Guide (English)]]
-  * [[http://wiki.hiorg-server.de/|Handbuch HiOrg-Server (german)]]
+  * [[http://wiki.fibu-schnittstelle.de|Financial accounting - webshop - interface (German)]]
-  * [[http://www.pkuinfo.it|PKUinfo: Informazioni, domande e risposte sulla fenilchetonuria]]
+  * [[http://wiki.hiorg-server.de/|Handbuch HiOrg-Server (German)]]
-  * [[http://davidak.de/wiki/|davidak wiki (german)]]
-  * [[http://weizhong-lab.ucsd.edu/cd-hit/wiki/|CD-HIT Wiki]]
-  * [[http://weizhong-lab.ucsd.edu/frhit/wiki/|FR-HIT Wiki]]
-  * [[http://www.anngon-wiki.info]] (Vietnamese)
-  * [[http://www.bluemel.eu|Versuch macht klug! Entdecke die Welt der Experimente mit A.Blümel]]
-  * [[http://sm.ingenieriamultimedia.org|course on Multimedia Engineering at University of Alicante]]
-  * [[http://dokuwiki.nausch.org|Djangos DokuWiki]] [[user>Django]]
   * [[http://manuals.lacie.com/en/manuals/bladerunner/|LaCie user manuals]]
-  * [[http://wiki.aeroseed.org/|AeroSeeD wiki]]
+  * [[http://mundoaz.com/wiki|Mundoaz - Satellite Decoders (Portuguese)]]
+  * [[http://www.pkuinfo.it|PKUinfo: Informazioni, domande e risposte sulla fenilchetonuria]]
+  * [[http://pe.hillschmidt.de|Prinz Eisenherz - Prince Valiant - Lexikon - Encyclopedia]]
+  * [[http://www.qem.eu/doku/doku.php|QEM srl manuals (Italian)]]
   * [[http://kantuz.esponde.net/|Wiki Kantuz]]
-  * [[http://www.estechnical.co.uk/docs|ESTechnical Documentation (English)]]
+  * [[https://webge.fr/dokuwiki|WEBGE wikis (french)]]
-  * [[http://pe.hillschmidt.de|Prinz Eisenherz - Prince Valiant - Lexikon - Encyclopedia]].
-  * [[http://www.qem.eu/doku/doku.php|QEM srl manuals (italian)]]
-  * [[http://www.laricetteria.net|LaRicetteria Recipes (italian)]]
-  * [[http://wiki.fibu-schnittstelle.de|financial accounting - webshop - interface (german)]]
-===== Linked Images =====
+===== Other info =====
+==== 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.
@@ Line 377: / Line 124: @@
 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 =====
+==== Password protection of generated documents ====
 To set fixed password for generated documents, edit:
-''dokuwiki/lib/plugins/dw2pdf/mpdf/config.php''
+''dokuwiki/lib/plugins/dw2pdf/mpdf/config.php'' (warning: each plugin update overwrites these changes)
 and add following lines:
@@ Line 392: / Line 139: @@
 (filips)
-===== iPhone/iPad =====
-When using with an iPhone/iPad disable the setting: Seiten mit gzip komprimiert ausliefern
+==== Hyphenation ====
-otherwise this plugin will not generate PDF-Files on iPhone/iPad.
-==== Discussion ====
+With the following setting in ''style.css'' it is possible to enable automatic hyphenation:
-=== Linked Images ===
+<code>
-Is it possible to somehow add a tutorial for how to get external embedded images into the pdf? i'd really appreciate that.
+body {
-=== Date format example ===
+   hyphens: auto;
-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 ===
+The hyphenation is of course language dependent. Normally, the wiki login language is used. If the [[translation|translation plugin]] is installed, the language selected here is used for hyphenation when creating the PDF.
-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 ===
+==== Rendering Limitations ====
-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.
+Because the rendering is done on the server side, plugins that rely on the client side to render might not do so correctly in the generated PDF.  Example: [[plugin:mermaid]]