Recent Changes - Search:

Cookbook

PmWiki

pmwiki.org

Mini

Summary: Simple, lightweight, un-bloated thumbnail and gallery generator
Version: 20140210
Maintainer: Petko
Discussion: Mini-Talk

Users: +28

License: GPL3+ (Mini, Ultralightbox), MIT (unverse.js)

Contents

Description

Simple, lightweight, un-bloated square thumbnail and gallery generator for PmWiki. Mini is a new image gallery and thumbnail generator for PmWiki.

Mini is used in the place of the PmWiki Attach: markup, but instead of displaying the original picture, a smaller version (thumbnail) is automatically created and displayed, with a link to the original file.

These pictures come from Public Domain collections at Wikimedia
Each thumbnail links to the original picture

The main differences from ThumbList are:

  • Square thumbnails. Mini extracts fixed-size thumbnails from the original pictures (default: squares).
  • Simpler. Easier to use than Thumblist. The script has very few options.
  • Un-bloated. Mini has only a few features, only the most needed ones for an online wiki gallery. No tables, no template trails, no unsupported filenames.
  • Ultralightbox. Mini works more easily and simply with Ultralightbox to produce high quality, special effects slideshows. It is easy to install other slideshows such as Lightbox and Fancybox.
  • Smaller and faster. The full script is 3 times smaller than the full Thumblist. It should load faster.
  • Integrated. Mini can be used with standard PmWiki markup dealing with images, including frames, tooltip titles, captions and links.

See also Mini vs Thumblist2 - discussion at the mailing list.

Examples

You can edit this page and link your Mini wiki-galleries below.

Installation

  • If you upgrade, please look first at the release notes.
  • Download the archive mini.zipΔ (alt. download: mini.zip).
  • Copy mini.php to your cookbook directory; copy the directory ultralightbox to your farm's /pub/ directory.
  • Add to local/config.php include_once("$FarmD/cookbook/mini.php");
  • Add to local/config.php $Mini['EnableLightbox'] = 1; (default is 0 (off), valid selections are 1, 2,or 3)
  • Add to a local CSS file, for example /pub/css/local.css, the line
    .mini { padding:2px; border:1px solid #dddddd; background-color:#ffffff; }
    .miniH, .miniF {display:block;}
  • Read also PmWiki.UploadsAdmin. Mini galleries are much easier to manage with the setting $UploadPrefixFmt = '/$Group/$Name'; (all pictures in a distinct directory per page).

Usage in a wiki page

Single thumbnails and lists:

  • Mini:picture.jpg produces a thumbnail of picture.jpg
  • Mini:pic1.jpg,pic2.jpg,pic3.jpg produces a list of selected thumbnails
  • Mini:* lists all thumbnails in the upload directory
  • Mini:r*,S*,t* lists pictures starting with R, S or T (case insensitive)
  • Mini:*.jpg,-pic1.jpg lists all JPGs except pic1.jpg
  • Mini:pic1.jpg,* first pic1.jpg, then all others (pic1 will not be repeated)
  • Mini:*,pic1.jpg same as the previous one; fully defined pictures are displayed before wildcard lists

Galleries of files, attached to a different wiki page:

  • Mini:Group.Page/picture.jpg one picture
  • Mini:Group.Page/pic1.jpg,pic3.jpg,pic2.jpg selected pictures in that order
  • Mini:Group.Page/* all pictures
  • Mini:Group.Page/*,-pic1.jpg all pictures except pic1.jpg
  • if you have per-group attachments, link to pictures in another group with the markup Mini:Group./picture.jpg (note the dot after the group)

Thumbnails from other groups or pages are created with the other groups/pages settings.

Tooltip titles and captions (both optional):

  • Mini:picture.jpg"A tooltip title" | A caption below the result is the same you would have with http://site/thumbnail.jpg"A tooltip title" | A caption below, see PmWiki.Images.
  • To remove the link title which is also the slideshow caption, you can use "-" in the title quotes: Mini:picture.jpg"-"
  • Detailed tooltip titles for individual (ordered) files:
Mini:OptionalOtherPage/[=
file1.jpg"Title of file1"
file2.jpg"Title of file2"
file4.jpg
file3.jpg
file5.jpg"Title of file5"
=]"Default tooltip, will be used for file4 and file3"

The recipe MiniEdit has a visual editor for Mini galleries, you can reorder, add or remove the pictures with your mouse, and set individual captions.

Thumbnails without links to the originals:

  • mini:picture.jpg   or   mini:* - lowercase "mini:" produces no links

Alternative links to pages/urls instead of to the originals:

  • [[Other page | mini:picture.jpg ]] - note the lowercase "mini:"
  • [[Other page | mini:picture.jpg"Tooltip title" ]] | Caption with [[link]] - you can have tooltips and captions too

List thumbnails in 4 columns, like in a table :

>>width=450px<<
Mini:*
>><<

The default thumbnails are 100 px wide, with some padding/margins between them, that's why we set width>400px for the div block.

Files not found

If you list in Mini:file.jpg a file that is not found in the uploads directory, the markup is transformed into a regular Attach:file.jpg link which allows you to upload a file with that filename. Note that Mini uses the same function as Attach: to search for the file; if the filename is not allowed by PmWiki, Mini: as well as Attach: links will fail to display it (and instead will offer a link to upload it with a standard filename).

Removing / regenerating the thumbnails

To remove all generated thumbnails, use a link [[Your page?action=purgethumbs]]. They will be recreated on the next page view. You may need to purge the thumbnails if you change some configuration variable, like Px, Quality or CropYPos, explained below.

Thumbnail sizes

Thumbnails attached to a page will all have the same dimensions (default: 100x100 pixels).

You can change the default size in a wiki page. Add this directive to your page:

   (:mini 160x100:)

and your thumbnails will be 160px wide and 100px high. The directive will override the $Mini['thumbs'][0] variable.

Note that the directive concerns only the files that are "uploaded" to the current page. If you have Mini:OtherGroup.Page/*, you need to add such a directive to OtherGroup.Page.

If you add or change the directive, you should purge the old thumbnails with [[Page?action=purgethumbs]].

Configuration

The following variables can be set in config.php before including the mini.php script. They can also be placed in local configuration files. (You do not need to add a line to config.php in case the default value suits you.)

Thumbnail format setting

  • $Mini['thumbs'][0] = "160x160"; change the thumbnail dimensions (width-x-height, default is 100x100 pixels)

The full thumbnail specification is in the following format:

 WIDTHxHEIGHTxCropXxCropYxQUALITYxBGCOLOR

With the default values:

 100x100x50x50x90xffffff

To change the default specification, write in config.php this line:

 $Mini['thumbs'][0] = '120x120x50x50x90xffffdd';

If you add or change the directive, you should purge the old thumbnails with [[Page?action=purgethumbs]].

Positioning the thumbnail

Thumbnails are square while original pictures may be rectangle. In this case, the thumbnail will be extracted from a square area in the original picture. By default, this square area is centered in the original picture, but you can change this.

In the full thumbnail specification:

 WIDTHxHEIGHTxCropXxCropYxQUALITYxBGCOLOR

the values CropXxCropY represent the position of the cropped area, and vary between 0 and 100 (default both are 50).

  • In vertical pictures, CropY=0 means the top of the original will be shown in the thumbnail, 100 means the bottom. If you are displaying primarily portraits of people, you may want to set it to 0.
  • In horizontal pictures CropX=0:left, 50:center, 100:right.

Ultralightbox

Ultralightbox is a package used to overlay images on the current page and display them in nice slideshows. In browsers without JavaScript it defaults to linking to the original picture. Here are the configuration settings:

  • $Mini['EnableLightbox'] = 1; to enable Ultralightbox slideshow mode 1 (default is disabled, can be 1, 2 or 3). There are three modes of slideshows:
    • 1 : all thumbnails in the page form an "image set"; with < and > arrows you can see them all
    • 2 : each Mini: set is in an independent "image set"; < and > arrows show only the pictures in the current Mini: markup
    • 3 : each thumbnail is independent; the original is displayed with Ultralightbox but no < and > arrows, and sliding to prev/next is disabled.
  • $Mini['LbUrl'] = '/pub/ultralightbox'; to change the location of the directory containing Ultralightbox; default is "$FarmPubDirUrl/ultralightbox"
Notes:
  • Ultralightbox has the essential slideshow features and is very simple, small and fast.
  • You can change for a different slideshow library, see for example Lightbox, Fancybox and Galleria which have different interfaces and more configuration options.
  • In order to let Ultralightbox images float over any Youtube (Flash) videos you might have on your page, z-index settings will not work. Instead, try adding ?wmode=transparent to your video code, as in: http://www.youtube.com/embed/0KDCp5dW590?wmode=transparent

Automatic renaming of files

Mini can display only files with simple filenames, that are also displayed by PmWiki's Attach: markup. That means no spaces or special or accented characters, and no uppercase extensions.

From version 20090321, Mini can automatically rename an existing file with a wrong filename, to one that is allowed. To enable this, add to config.php this line:

  $Mini['FixFilenames'] = 1;

This will convert the extension to lowercase, spaces to underscores "_", and will strip all problematic characters.

Full gallery cache

From version 20090104, a full caching of the Mini: galleries in the page can be enabled. It functions like the Thumblist's Supercache feature, however it is simpler and slightly faster.

On pages with a huge number of thumbnails like here, the full cache greatly reduces the server/filesystem load and the page displays much more quickly.

To enable the full cache, set this line in config.php or in a local customization file:

 $Mini['EnableCache'] = 1;

Note that if you add, delete or re-upload a picture that should appear in a page, you need to re-edit the page so that the cache gets rebuilt.

Also note that caching is not designed to work inside or after ConditionalMarkup that modifies the number or the order of the Mini sets. (You can reliably cache only pages displaying the same galleries to every reader.)

If cache is enabled and you move your wiki to a different server, you may have to either delete the (hidden) *.mini-cache.txt files in the uploads directories, or edit and save the gallery pages.

Title and text around the gallery

It appeared to me that I often need to repeat the tooltip title as a text right before or after the Mini: line:

'''Some title text'''
Mini:a*.jpg"Some title text"

or:

Mini:b*.jpg"Some additional text"
Some additional text

This repetition is annoying and the page source becomes less readable, and more difficult to edit for authors. This was simplified in version 20090201. If you set in config.php $Mini['EnableHeaderFooter']=1; then you can write in the quoted "tooltip" both the heading title text and the footer additional text:

Mini:a*.jpg"Title text before|Additional text after"

A vertical bar | separates the title header and the footer. Both are not required, use Mini:*.jpg"Title|" to have only a title. The vertical bar will be removed from the tooltip.

If you don't have a vertical bar in your quoted tooltip, no header or footer are printed.

You can style differently the header title and the footer by adding to pub/css/local.css such a sample code .miniH {font-weight: bold;} for a bold header title.

Rectangle thumbnails

The default Mini installation produces square thumbnails which are cropped from a square region in the original picture. While squares look and combine better, in some cases, if all pictures are of the same proportions, it may be desirable to have rectangle thumbnails.

From version 20090513, it is possible to set in config.php a custom thumbnail size. Examples :

  • $Mini['thumbs'][0] = '120x90'; force thumbnails to 120x90 instead of 100x100

Note that all thumbnails attached to the same page will have the same proportions, regardless of the proportions of the originals.

If you change the variable $Mini['thumbs'], or if you use the (:mini 160x200:) directive you should purge the old thumbnails with [[Page?action=purgethumbs]].

These variables can be overridden by the (:mini 160x200:) directive in the wiki page.

Custom Mini sets (advanced users)

Version 20090513 has new possibilities of customization. Most importantly, you can now have different Mini thumbnails for one picture, by using Mini1:*.jpg, Mini4:*.jpg, Mini9:*.jpg, instead of Mini:*.jpg.

You can have up to 10 different settings for thumbnails. In config.php, you can set:
  $Mini['thumbs'][0] = "120x120x50x0x90xffffff";  # For Mini:
  $Mini['thumbs'][1] = "80x80x50x50";             # For Mini1:
  # ... #
  $Mini['thumbs'][9] = "0x128";                   # For Mini9:

The full thumbnail specification is:

 WIDTHxHEIGHTxCropXxCropYxQUALITYxBGCOLOR

Only the WIDTHxHEIGHT in pixels are required; the other values have default settings.

If you set both WIDTH and HEIGHT, the thumbnail will have the exact size. If one of these values is 0, this dimension of the thumbnail will be calculated to be proportional to the other one. For example :

  • 100x100 produces thumbnails all 100x100 pixels, regardless of the original size and proportion (extremities will not appear in the thumbnail)
  • 0x128 produces thumbnails all 128px high, the width depending on the original picture, exactly like in ThumbList.
  • 140x0 produces thumbnails all 140px wide, the height set automatically.
You can also set these sizes in the wiki page via the directive:
(:mini 120x120:) or
(:mini m1=80x80 m2=90x45 m3=141x100 m9=0x128x50x0x90x000000:)

In this case, the m1= parameter refers to Mini1: sets, m2= to Mini2: sets, etc. Bear in mind the restrictions regarding these directives: they only apply to image files loaded to the present page (or to the present group, if files are loaded per-group).

Demos.

Recipes for extended features

Mini can be extended via recipes. This allows wiki admins to have more features while keeping the core distribution smaller and simpler.

Notes

Unlike ThumbList, Mini does not work with non-standard filenames, unrecognized by the PmWiki core (like: filenames with spaces or uppercase extensions). Mini is only expected to work if the same file can be displayed both with an Attach: link, and in the (:attachlist:) directive. The best way to have "standard" filenames is to upload your files by the PmWiki's ?action=upload function.

The thumbnails are stored in the same directory as the original pictures. They are created only once (or if the original pictures are modified). If you change some configuration variable like $Mini['thumbs'][0], you need to purge the thumbnails in order to let Mini recreate them with the new parameters. Purging the thumbnails is done with [[Page?action=purgethumbs]].

Like ThumbList, Mini can work with $EnableDirectDownload set to 0, and with any $UploadPrefixFmt settings.

The easiest way to create wiki galleries is to enable uploads "per-page" instead of the PmWiki's default "per-group". See UploadsAdmin and $UploadPrefixFmt.

Note that the thumbnails are created with "action=mini" in the url address. If your config.php restricts the actions your visitors can perform, you may want to allow the 'mini' action. See also PmWiki:AvailableActions.

Change Log / Release Notes

  • 20140210 : Update for PHP 5.5.
  • 20121204 : Ultralightbox : remove prev/next navigation for single picture sets.
  • 20120913 : fix a bug added in 20120831 which broke captions.
  • 20120831 : Ultralightbox : remove prev/next navigation for "mode 3".
  • 20120725 : Ultralightbox : fix keyboard shortcuts; add LB.F delay for fade-in animations.
  • 20110828 : minor changes in markup caching for a future MiniEdit recipe.
  • 20110824 : minor changes to allow quotes in captions (use &quot;) and text caching for a future MiniEdit recipe.
  • 20110817 : The slideshow integration format changed to make it much easier to install other packages. The slideshow package was changed from Lightbox to Ultralightbox which is simpler and more minimalist. To continue using Lightbox with newer Mini versions, see MiniLightbox.
  • 20110815 : custom html templates ImgFmt and LinkFmt can access more variables.
  • 20110811 : enabled detailed file/tooltip lists.
  • 20110527a : fix broken html tags in tooltip titles, reported by Oliver Betz.
  • 20110522 : updated Lightbox to version 2.05 (mini.php and all *.js and *.css files need to be replaced). Added a file lightbox-mini.js which should ease future Lightbox upgrades by simply replacing the files. Added parameters $Mini['PurgeRedirectFmt'] to configure the redirection after a purge, $Mini['nofileurl'] to customize the link when the requested file doesn't exist (default is an attach link to upload the file). You can now have different $Mini['ImgFmt#'], $Mini['LinkFmt#'], $Mini['MiniFmt#'] (#=0..9) html templates for the different Mini0:..Mini9: advanced galleries.
  • 20100413 : updated Lightbox to version 2.04. If you upgrade, mini.php and all *.js and *.css files need to be replaced.
  • 20100210 : Add variable $Mini['CreateFunction'] to allow custom processing functions (example).
  • 20090513 : Major changes (if you upgrade, read this)
    • Mini has now a highly flexible ways to define thumbnail sizes, qualities, crop-position.
    • It is now possible to have up to 10 thumbnails with different sizes from one picture.
    • Removed (:mini x=## y=##:). If you have used the directive, replace it with (:mini WIDTHxHEIGHT:).
    • Removed variables LbMaxH, LbMaxW, Px, Py, Quality, CropYPos, CropXPos. If you have used these variables, you can now replace them with one line:
      $Mini['thumbs'][0] = "120x120x50x0x90xffffff";, read the Configuration section.
    • Removed core IPTC extraction. A recipe is provided for those who require it.
    • Added a hook to manipulate the file list, see the recipe random thumbnails as an example.
    • The tooltip-caption can be processed with user functions (see the IPTC recipe for example).
  • 20090321 : added automatic renaming of files to supported filenames, simplified default slide caption.
  • 20090221 : added (:mini x=## y=##:) directive.
  • 20090215 : fixed a buggy call to a debug function, caught by Rogut279s.
  • 20090202 : added $Mini['Py'] to enable rectangle thumbnails
  • 20090201 : added $Mini['EnableHeaderFooter'], small change to the suggested CSS code to be installed
  • 20090104 : added full gallery caching
  • 20081216 : added experimental IPTC caption extraction
  • 20081211 : fixed escaped twice html entities in link titles (appeared for characters like &, <, > and " in link titles).
  • 20081202 : fixed a bug with "-" with 2+ thumbnails.
  • 20081124 : added "-" to remove the link title and Lightbox caption.
  • 20080924 : the program will display a message if the GD image library is not enabled.
  • 20080717b : fixed a bug introduced earlier today with LbMaxH and LbMaxW (reported by Damien); $FarmPubDirUrl is left to be expanded on output (suggested by Pm).
  • 20080717 : fixed $FarmPubDirUrl if unset; changed default LbMaxH and LbMaxW to 0 (disabled).
  • 20080713b : thumbnails are now subtly sharpened, if your PHP supports imageconvolution; added Lightbox modes
  • 20080713 : initial public release

See Also

  • MiniEdit -- An easy to use visual editor for Mini galleries
  • SystemLimits -- If Mini seems unable to create a thumbnail, you may need to increase some time and memory limits of the system.
  • ThumbList -- Another gallery script with different markup, configuration options and parameters.
  • Maxi -- An image viewer with inline zoom, suitable for large drawings or panoramas.
  • YAG -- "Yet Another Gallery tool" - Create thumbnail gallery of large number of images distributed over multiple pages.

Authors

Mini is written and maintained by Petko. The script is partially based on ThumbList (also by Petko) and on PmWiki's uploads.php script by Pm. Ultralightbox is written by Petko Yotov. The Unverse.js library is written by John Goodman.

Comments

Your comments are welcome at Mini-Talk.

User ratings / Votes

You can edit this page and add your name. Please don't add a vote (+) or (-) if you already added one in the example galleries linked above.

  • Your name here
  • (+) Fine for the simple album I wanted to organize. Hugh (5/2014)
  • (+) Simple, flexible and beautiful. You can't ask for more. AdamShand
  • (+) Simple to use, yet powerful. A great extension you'll get in love with. Thanks! simkin November 09, 2011, at 05:33 AM
  • (+) Useful! TeganDowling February 01, 2010, at 03:01 PM
  • If you you have something to do with images, use this. It's very flexible and the support is good and fast. Matthias Günther February 21, 2010, at 03:41 PM
  • (+) Very easy to use and very impressive results. Good work! MKonrad May 11, 2010, at 10:30 AM
  • (+) Great! OliverBetz 2010-05-14
  • (+) Great extension, very useful and really easy to use. Georges Schutz February 21, 2009, at 08:55 AM
  • (+) Thanks for your help and tips! Greetings, -- miranon, 3 december 2008
  • (+) I have been looking for a solution like this for such a long time. Thank you for such a wonderful work! -- JLuk, October 27, 2008
  • (+) Simple and easy to integrate/use. Michael Paulukonis February 11, 2014, at 08:06 AM
  • (+) It's all been said. One more thing, looks good on mobile devices, too. TomG 2014-02-24

User notes +28: If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.

Edit - History - Print - Recent Changes - Search
Page last modified on December 17, 2014, at 08:08 AM