Summary: Simple, lightweight, un-bloated thumbnail and gallery generator
Version: 20090104
Description
Simple, lightweight, un-bloated square thumbnail and gallery generator for PmWiki.
Mini is a new image gallery and thumbnail generator for PmWiki. It was born out of the well known ThumbList.
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 square thumbnails from the original pictures. Squares combine better and arguably look better.
- Simpler. Easier to use than Thumblist. The script has very few options, none of which is written in the wiki page. The only wiki markup is
Mini:image.jpg.
- Un-bloated. Mini has only a few features, only the most needed ones for an online wiki gallery. No tables, no template trails, no captions, no multiple thumb sizes, no unsupported filenames.
- Lightbox. Mini works more easily and simply with Lightbox to produce high quality, special effects slideshows.
- Smaller and faster. The full script is 5 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.
Mini is also compatible with Thumblist : it is possible to use both recipes at the same time.
Examples
Please edit this page and link your Mini wiki-galleries below.
Installation
- Download the archive mini.zipΔ (alt. download: mini.zip).
- Copy
mini.php to your cookbook directory; copy the directory lb (the Lightbox files) to your farm's /pub/ directory.
- Add to local/config.php
include_once("$FarmD/cookbook/mini.php");
- Add to a local CSS file, for example /pub/css/local.css, the line
.mini { padding:2px; border:1px solid #dddddd; background-color:#ffffff; }
- Read also PmWiki.UploadsAdmin. Mini galleries are much easier to manage with the setting
$UploadPrefixFmt = '/$Group/$Name';
This recipe is postcardware. If you like it, you can send me a postcard. I have recieved 1 postcard for Mini. :-)
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/* all pictures
- 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"-"
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 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.
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.)
Thumbnails
$Mini['Px'] = 160; change the thumbnail dimensions (default is 100 pixels)
$Mini['Quality'] = 95; change the JPEG quality of the thumbnails; default is 90; 100 is best, but the file size gets bigger
$Mini['BgColor'] = array(0xff, 0xff, 0xff); the background color of the thumbnails, in Red-Green-Blue notation (similar to #ffffff for white). The background will be visible if a picture has transparency, or if it is smaller than the thumbnail size, in that case it will be centered in the thumbnail canvas. Demo.
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.
$Mini['CropYPos'] = 0.2; (must be between 0.0 and 1.0, default is 0.5) vertical position of the cropped area, when the picture is vertical. 0 means the top of the original will be shown in the thumbnail, 1 means the bottom. If you are displaying primarily portraits of people, you may want to set it to 0.
$Mini['CropXPos'] = 0.5; position of the crop window for horizontal pictures (0:left, 0.5:center, 1:right).
Lightbox
Lightbox [1] is an unobtrusive JavaScript used to overlay images on the current page and display them in nice slideshows. And in browsers with JavaScript turned off it simply defaults to linking to the original picture. Here are the configuration settings:
$Mini['EnableLightbox'] = 1; to enable Lightbox slideshow mode 1 (default is disabled, can be 1, 2 or 3). There are three modes of Lightbox 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 Lightbox but no < and > arrows, and sliding to prev/next is disabled.
$Mini['LbUrl'] = '/pub/lb'; to change the location of the lb directory containing Lightbox; default is "$FarmPubDirUrl/lb"
$Mini['LbMaxH'] = 800; $Mini['LbMaxW'] = 800; the maximum height and width of the original pictures to be inserted in a Lightbox slideshow. If a picture is bigger, Lightbox is disabled for it, and it is displayed directly in the browser. These options exist because if a visitor has a smaller screen than the picture, playing it in Lightbox may not be nice. Default value for both options is "0", and all pictures are displayed in Lightbox.
IPTC captions
From version 20081216, Mini is able to display as captions and tooltips the IPTC captions. These are embedded in the picture by a camera or by an editing software like the GIMP, IrfanView, Picassa, Photoshop etc. Some people find it easier to annotate their pictures in an editor than in the wiki page.
Not all pictures contain IPTC tags.
To enable IPTC extraction, you need two things:
- in config.php, the line
$Mini['GetIPTC'] = 1;
- in the wiki page, do not set a tooltip title in quotes after the Mini: markup.
The IPTC standard was poorly designed about embedded texts (IMHO), and various picture editing software do not implement it the same way, so there may be problems for some non-ascii characters. In that case, you can define the source encoding of the caption:
$Mini['GetIPTC'] = "ISO-8859-1"; # in most cases, OR
$Mini['GetIPTC'] = "Windows-1251";# older Cyrillic encoding
Thus Mini will try to convert the captions to display them correctly in your page. (Not all PHP installations can convert between charsets.)
Extracting IPTC captions from pictures adds some load to your server and could make the page display slower. Also, I find it easier to create and modify captions directly in the wiki page:
Mini:1.jpg"Caption 1" \
Mini:2.jpg"Caption 2" \
Mini:3.jpg"Caption 3"
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.)
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['Px'], 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]].
Thumbnails will all have the same dimensions (default: 100x100 pixels). You can have different sizes on different groups or pages via standard per group customization. To have different size thumbnails on the same page, you can upload them in a different wiki page and change the configuration settings for that page.
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.
Change Log / Release Notes
- 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
- ThumbList, another gallery script with more features, and much more configuration options and parameters.
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.
Lightbox [2] and its underlying libraries are written by a number of people. See source files for authors and free software licenses. Lightbox was slightly modified by Petko to work with PmWiki directories and the recipes ThumbList and Mini.
Comments
Your comments are welcome at Mini-Talk.
