1====== mediathumbnails Plugin ====== 2 3---- plugin ---- 4description: Extracts a thumbnail from media files (ODT, DOCX, PPTX, PDF, JPG, etc.) in a media library and shows it on the wiki page. 5author : Thomas Schäfer 6email : thomas@hilbershome.de 7type : syntax 8lastupdate : 2021-05-24 9compatible : 2020-07-29 "Hogfather" 10depends : 11conflicts : 12similar : 13tags : images, media, mediamanager, thumbnail, odt, pdf 14 15downloadurl: https://github.com/ternite/dokuwiki-plugin-mediathumbnails/archive/v0.92.zip 16bugtracker : hhttps://github.com/ternite/dokuwiki-plugin-mediathumbnails/issues 17sourcerepo : https://github.com/ternite/dokuwiki-plugin-mediathumbnails 18donationurl: 19 20screenshot_img : 21---- 22 23===== Installation and Dependencies ===== 24 25Install the plugin using the [[plugin:plugin|Plugin Manager]] and the download URL above, which points to latest version of the plugin. Refer to [[:Plugins]] on how to install plugins manually. 26 27:!: **External requirements:** Office files (ODT, DOCX, PPTX, etc.) are supported natively. If you need image or PDF support, this plugin requires the following additional components that must be installed and integrated into your PHP environment separately: 28 29 * Support for Office file thumbnails: 30 * [[https://www.php.net/manual/de/book.zip.php|zip]] PHP extension 31 * libzip-dev (needed by zip) - your installation might already have this installed, or not. 32 * Support for PDF and image thumbnails: 33 * [[https://imagemagick.org|ImageMagick]] 34 * [[https://github.com/Imagick/imagick|Imagick]] (PHP extension for ImageMagick integration) 35 * [[https://www.ghostscript.com/index.html|GhostScript]] //(obligatory only for PDF support)// 36 37Hints: 38 * Installation on Windows was troublesome for me. The best description of how to install ImageMagick and Imagick was: [[https://mlocati.github.io/articles/php-windows-imagick.html|Install the ImageMagick PHP extension in Windows]] by [[https://github.com/mlocati|Michele Locati]]. 39 * It does not cover the installation process of ImageMagick, but the correct destribution archive is linked along with the matching PHP extension! 40 * In addition to the description on Michele's page, I added ImageMagick's bin folder to my systems' PATH variable and to a variable named MAGICK_HOME. 41 * Concerning the installation of GhostScript: despite all my efforts, wedding GhostScript to ImageMagick via configuration failed. I finally added GhostScript's `bin` folder to the System Environment PATH variable (which is ok) and then I renamed `gswin32c.exe` to `gs.exe` (then I made my donut suffer for it). 42 * You might run into a case where ImageMagick, Imagick and Ghostscript are properly installed, but no PDF file thumbnail is created. (In that case, you should get a proper error message if you activated //allowdebug// in your dokuwiki config.) This may be due to a security policy defined in ImageMagick's `policy.xml`. Look for the following entry, then change the //rights// attribute to the value `read|write`: 43 44<code><policy domain="coder" rights="none" pattern="PDF" /></code> 45 46...should become... 47 48<code><policy domain="coder" rights="read|write" pattern="PDF" /></code> 49 50 * I also wrote a Dockerfile that takes care of the modules to be installed, and makes config adjustments within ImageMagick. It may help you in case you're using Docker: 51 52<code> 53FROM php:7-fpm 54 55RUN apt-get update && apt-get install -y \ 56 imagemagick libmagickwand-dev \ 57 libzip-dev \ 58 libgs-dev \ 59 ghostscript --no-install-recommends \ 60 && pecl install imagick \ 61 && docker-php-ext-enable imagick \ 62 && pecl install zip \ 63 && docker-php-ext-enable zip 64 65# Adjust ImageMagick security policy to allow PDF conversion 66ARG imagemagic_config=/etc/ImageMagick-*/policy.xml 67 68RUN if [ -f $imagemagic_config ] ; then sed -i 's/<policy domain="coder" rights="none" pattern="PDF" \/>/<policy domain="coder" rights="read|write" pattern="PDF" \/>/g' $imagemagic_config ; else echo did not see file $imagemagic_config ; fi 69</code> 70 71===== What's it for? ===== 72 73This plugin will show thumbnail images for supported media files (ODT, DOCX, PPTX, PDF, JPG, etc.) within your wiki pages. 74 75In default settings, a click in the thumbnail will have your browser download the media file. 76 77And an error message will be shown by default in case a referenced media file does not contain a thumbnail (office files) or is an unsupported file type (see dependencies on how you might work around that). 78 79===== Syntax ===== 80 81<code>{{thumbnail>media_path_and_filename}}</code> 82 83Shows a thumbnail of the media file given via the string `media_path_and_filename` (standard file path for the [[:media_manager|Media Manager]]). In case of an office file (ODT, DOCX, PPTX, etc.), this will only work, if a thumbnail image already has been saved within the file (which nowadays should be very common). 84 85In order to be able to show the thumbnail image, the image itself is stored within the media library alongside the media file (see [[#Implementation Details|Implementation Details]]). 86 87The plugin watches file changes at the moment a wiki page is rendered. You might need to watch out for page caching! 88 89In case a media file is replaced by another file (with the same name), this will be noticed by timestamp comparison - the original thumbnail will be overwritten. 90 91**Example:** <code>{{thumbnail>main:media_namespace:presentation.pptx}}</code> 92 93This will show a thumbnail of the Powerpoint presentation in your wiki page. The thumbnail image will be stored within the media library as `main:media_namespace:presentation.pptx.thumb100.jpeg` (with default settings, and because JPEG appears to be the format of thumbnail images within a PPTX file). 94 95===== Implementation Details ===== 96 97In all cases where a file format is supported by the plugin, it will add a thumbnail image into the [[:media_manager|Media Manager]]. In case you decide later on that you don't want these images within your media, your only option is to remove them manually. 98 99The name of the thumbnail will be: <code>{original_filename}.thumb{thumb_max_dimension}.{image_suffix}</code> 100 101The following examples assume the default value of 100 for `thumb_max_dimension`. 102 103**Example 1:** my_dog.jpg => my_dog.jpg.thumb100.jpg 104 105**Example 2:** presentation.pdf => presentation.pdf.thumb100.jpg 106 107The file format for PDF thumbnails will always be JPG. 108 109**Example 3:** presentation.pptx => presentation.pptx.thumb100.png 110 111Note that the file format of the thumbnail in office files might theoretically be any image file format. It depends on the format found within the office file. If you use office files with differing file formats, you might need to adjust the config setting `thumb_paths`. If you have such an office file, I'd like to hear about that so I can add the format to the default value of that config option. 112 113==== Office files ==== 114 115When looking for thumbnails of office files (ODT, DOCX, etc.), the plugin essentially assumes these files to be ZIP files containing a thumbnail image at a specific path (see config setting `thumb_paths`). It will not generate any images for office files, but look for an already embedded thumbnail within the document file, then show the thumbnail on your wiki page. 116 117==== Image files ==== 118 119The plugin will need a properly installed and integrated **ImageMagick** and **Imagick** suite (see [[#Installation and Dependencies]]). Then it will load the image into ImageMagick and transform it into a thumbnail image. 120 121==== PDF files ==== 122 123In order to create thumbnails for PDF files, in addition to a requirement of **ImageMagick** and **Imagick**, you will also need a properly installed and configured **GhostScript** (see [[#Installation and Dependencies]]). The plugin will then transform the first page of the PDF file to a JPG thumbnail. 124 125===== Configuration and Settings ===== 126 127//(compare: [[:devel:configuration#configuration_metadata|Configuration metadata]] for configuration classes)// 128 129^ **thumb_max_dimension** | Default dimension to set for a thumbnail (in pixels, enter without units). The thumbnail will fit into a quadratic box of this size - in case the image is not quadratic, the other dimension will be reduced per aspect ratio. || 130| ::: | numeric, default: | **"100"** | 131^ **thumb_paths** | Paths within media files (format: ZIP) to look at for thumbnail images (comma-separated list, use slashes as directory delimiters). //Is defaulted for paths within ODT files and MS Office files, but can be extended in case of other formats.// || 132| ::: | array, default: | **array("Thumbnails/thumbnail.png", "docProps/thumbnail.jpeg")** | 133^ **link_to_media_file** | Should a click on the thumbnail start the media file download? || 134| ::: | onoff, default: | **true** | 135^ **show_no_thumb_error** | In case no thumbnail was found, do you want an error message be shown? || 136| ::: | onoff, default: | **true** | 137^ **no_thumb_error_message** | Error message to be shown when no thumbnail was found, and 'show_no_thumb_error' is set. Media path will automatically be appended! || 138| ::: | string, default: | **"No thumbnail in "** \\ //note: media path will automatically be appended// | 139 140If your PDF and/or image thumbnails don't show up, consider activating the `allowdebug` option in the DokuWiki base configuratoin. I added some checks that should output information on dependency status. 141 142===== Development ===== 143 144[[https://github.com/ternite/dokuwiki-plugin-mediathumbnails|Sources]] on github. 145 146=== Change Log === 147 148 * **2021-03-29** 149 * v0.81 (Initial release) 150 * **2021-04-02** 151 * v0.91 (added image and PDF support) 152 * config option `thumb_width` was dropped, so you might want to delete that entry from `conf/local.php` if you upgraded from v0.81 and had altered that value 153 * **2021-05-24** 154 * v0.92 (Added checks for ImageMagick security policy issues) 155 156=== Known Bugs and Issues === 157 158See [[https://github.com/ternite/dokuwiki-plugin-mediathumbnails/issues|issue tracker]] on github. 159 160===== FAQ ===== 161 162None, yet. 163 164===== Discussion ===== 165 166//Thomas Schäfer (2021-03-29):// I wasn't able to locate a proper specification indicating the exact file locations for thumbnails within both OpenOffice/LibreOffice files, or MS Office files. In case you point me to such a specification, I might enhance the config settings for properly identifying thumbnails in more instances of such office documents.
