plugin ---- description: Extracts a thumbnail from media files (ODT, DOCX, PPTX, PDF, JPG, etc.) in a media library and shows it on the wiki page. author : Thomas Schäfer email : thomas@hilbershome.de type : syntax lastupdate : 2021-05-24 compatible : Hogfather, Igor depends : conflicts : similar : tags : images, media, mediamanager, thumbnail, odt, pdf
downloadurl: https://github.com/ternite/dokuwiki-plugin-mediathumbnails/archive/v0.92.zip bugtracker : hhttps://github.com/ternite/dokuwiki-plugin-mediathumbnails/issues sourcerepo : https://github.com/ternite/dokuwiki-plugin-mediathumbnails donationurl:
screenshot_img :
This plugin will show thumbnail images for supported media files (ODT, DOCX, PPTX, PDF, JPG, etc.) within your wiki pages.
In default settings, a click in the thumbnail will have your browser download the media file.
And 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).
Install the plugin using the Plugin Manager and the download URL above, which points to latest version of the plugin. Refer to :Plugins on how to install plugins manually.
- !: **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:
* Support for Office file thumbnails:
* [[https://www.php.net/manual/de/book.zip.php|zip]] PHP extension
* libzip-dev (needed by zip) - your installation might already have this installed, or not.
* Support for PDF and image thumbnails:
* [[https://imagemagick.org|ImageMagick]]
* [[https://github.com/Imagick/imagick|Imagick]] (PHP extension for ImageMagick integration)
* [[https://www.ghostscript.com/index.html|GhostScript]] //(obligatory only for PDF support)//
Hints:
* ImageMagick installation might be troublesome. At least it was for me. My installation routine on Windows 10 x64 in detail:
* Install ''Ghostscript 9.56.1'' ([[https://github.com/ArtifexSoftware/ghostpdl-downloads/releases/download/gs9561/gs9561w64.exe|gs9561w64.exe]]).
* Ascertain that GS's ''bin'' folder was added to the System PATH variable.
* Install ''ImageMagick 7.1.0'' for x64 ([[https://windows.php.net/downloads/pecl/deps/ImageMagick-7.1.0-18-vc15-x64.zip|ImageMagick-7.1.0-18-vc15-x64.zip]]) by executing the following steps:
* Extract the ZIP's content to ''C:\Program Files\ImageMagick-7.1.0-18-vc15-x64''.
* Add ''C:\Program Files\ImageMagick-7.1.0-18-vc15-x64\bin'' to the System PATH variable manually.
* Open ''C:\Program Files\ImageMagick-7.1.0-18-vc15-x64\bin\policy.xml'' and either add the following line within ''<policymap>..</policymap>'': ''<policy domain="coder" rights="read|write" pattern="PDF" />''. If a similar line containing domain ''coder'' and pattern ''PDF'' already exists, change it accordingly.
* Install ''ImageMagick PHP extension'' ([[https://windows.php.net/downloads/pecl/releases/imagick/3.7.0/php_imagick-3.7.0-7.4-ts-vc15-x64.zip|php_imagick-3.7.0-7.4-ts-vc15-x64.zip]]) by executing the following steps:
* Extract all ''CORE_RL_*'', ''FILTER_*'' and ''IM_MOD_RL_*'' from the ZIP's content to ''C:\Program Files\ImageMagick-7.1.0-18-vc15-x64\bin''. Accept overwriting all files that may already be present there. Yes, that's the binaries folder of the ImageMagick installation.
* Extract ''php_imagick.dll'' to ''{PATH_TO}\php\ext''.
* Open ''{PATH_TO}\php\php.ini'' and add a line ''extension=imagick''. If using earlier versions of the software involved, you may have to try a combination like ''php_imagick'', ''imagick.dll'', ''php_imagick.dll''.
* Don't forget to restart the webserver.
* If you want or have to install another version, this might be a useful resource: [[https://mlocati.github.io/articles/php-windows-imagick.html|Install the ImageMagick PHP extension in Windows]] by [[https://github.com/mlocati|Michele Locati]]. It helps you identify the correct version of php_imagick in relation to your PHP installation. Formerly, you also got a download link for the appropriate version of ImageMagick, but the version of this page I visited today appears to not do that anymore.
* I also wrote a Dockerfile (for an earlier installation / version constellation) that takes care of the modules to be installed, and makes config adjustments within ImageMagick (only works if the policy domain ''coder'' is predefined in ''policy.xml'' - it's not in the recent versions I came accross). It may help you nevertheless, in case you're using Docker:
FROM php:7-fpm
RUN apt-get update && apt-get install -y \
imagemagick libmagickwand-dev \
libzip-dev \
libgs-dev \
ghostscript --no-install-recommends \
&& pecl install imagick \
&& docker-php-ext-enable imagick \
&& pecl install zip \
&& docker-php-ext-enable zip
# Adjust ImageMagick security policy to allow PDF conversion
ARG imagemagic_config=/etc/ImageMagick-*/policy.xml
RUN 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
{{thumbnail>media_path_and_filename}}
Shows a thumbnail of the media file given via the string `media_path_and_filename` (standard file path for the 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).
In 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).
The plugin watches file changes at the moment a wiki page is rendered. You might need to watch out for page caching!
In 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.
- Example:**
{{thumbnail>main:media_namespace:presentation.pptx}}
- Example:**
In all cases where a file format is supported by the plugin, it will add a thumbnail image into the 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.
The name of the thumbnail will be: {original_filename}.thumb{thumb_max_dimension}.{image_suffix}
The following examples assume the default value of 100 for `thumb_max_dimension`.
- Example 1:** my_dog.jpg => my_dog.jpg.thumb100.jpg
- Example 2:** presentation.pdf => presentation.pdf.thumb100.jpg
- Example 3:** presentation.pptx => presentation.pptx.thumb100.png
When 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.
The 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.
In 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.
//(compare: Configuration metadata for configuration classes)//
^ **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. || | ::: | numeric, default: | **"100"** | ^ **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.// || | ::: | array, default: | **array("Thumbnails/thumbnail.png", "docProps/thumbnail.jpeg")** | ^ **link_to_media_file** | Should a click on the thumbnail start the media file download? || | ::: | onoff, default: | **true** | ^ **show_no_thumb_error** | In case no thumbnail was found, do you want an error message be shown? || | ::: | onoff, default: | **true** | ^ **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! || | ::: | string, default: | **"No thumbnail in "** \\ //note: media path will automatically be appended// |
If 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.
Sources on github.
* **2021-03-29**
* v0.81 (Initial release)
* **2021-04-02**
* v0.91 (added image and PDF support)
* 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
* **2021-05-24**
* v0.92 (Added checks for ImageMagick security policy issues)
See issue tracker on github.
None, yet.
//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.