Summary: Simple, lightweight, un-bloated thumbnail and gallery generator
Version: 20150405
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.
Each thumbnail links to the original pictureThe 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
- 20150405 : Small fixes for PHP 5.5. The recipe now requires PmWiki 2.2.58 or more recent.
- 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 ") 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.