Summary: WikiGallery - automatic easy to use fully integrated gallery extension for PmWiki
Prerequisites: PmWiki 2.1 or 2.2beta, ImageMagick (aka convert command), libgd2 support in PHP or PhpThumb


Version: $Rev: 67 $
Maintainer: None (original author: sts)
Categories: Images, CustomPageStore
Discussion: WikiGallery-Talk

Note: This recipe is unmaintained, it is not recommended to use it for new projects. See Mini or ThumbList for supported PmWiki gallery recipes. If you already use WikiGallery and a PHP upgrade broke it, there is a GitHub repository with more recent code you can try.

Questions answered by this recipe

  • How do I create a photo gallery
    • which is fully integrated into PmWiki?
    • which works just by uploading pictures into a directory with FTP/SCP?
    • which is easily customizable with PmWiki pagelist syntax?
    • which allows you to use thumbnails of your gallery pictures everywhere in the wiki?



WikiGallery creates a photo group (e.g. "Pics") inside your PmWiki. Photos are taken from a directory which you can fill using your favourite FTP (or SCP, or whatever) client. Inside of the group every photo will get a wiki page, derived from its filename. Every directory will get an overview page. All the markup is done using normal wiki pages (as templates) and a combination of (dynamic) trail and pagelists. So everything should be highly customizable to fit your needs.

Usage Example

If you want to publish a directory with JPG images from your camera, what you do is the following (assume Pics as the photo group):

  • upload the pictures into a subdirectory of your photo directory on the server (e.g. "/http/pictures/Xmas 2005")
  • goto the page Pics/Xmas2005, you will see a list of thumbnails.
  • click on a photo, you will get the big version of the photo, e.g. Pics/Xmas2005-XmasEve123
  • click at the small thumbnails above the photo to go to the next photo in the directory
  • Edit a photo page and set the title by using the usual (:title... markup
  • Let people comment on your pictures (using one of the comment recipes)

Release Notes

If the recipe has multiple releases, then release notes can be placed here. Note that it's often easier for people to work with "release dates" instead of "version numbers".

  • 2007-03-27 show random picture recursively if a folder only contains other folders, but not pictures
  • 2007-03-27 don't output stupid URLs for invalid pictures
  • 2007-03-24 added JamesM's patch to allow picture size in width and height
  • 2007-03-24 added w:h! notation (borrowed from ImageMagick)
  • 2007-03-24 added (:gallerypicturepage filename:) markup to return the page name for a picture filename
  • 2007-03-22 removed thumb style from lframe in album list. It explicitly sets the image width to 100px which might not be what you expect.
  • 2007-03-12 add globals (thanks again to JamesM)
  • 2007-03-12 Use $DefaultName instead of HomePage (thanks to JamesM)
  • 2007-03-12 avoid long lines in overview (thanks to JamesM and Lighans)
  • 2006-11-27 Zero-size files are seen as non-existant. Hopefully catch some installation errors with that
  • 2006-11-16 Typo corrected, slideshow should work again
  • 2006-11-13 RecipeInfo line
  • 2006-11-13 Added $WikiGallery_UseFlatCache to use flat cache filenames by default because some servers cannot cope with mkdirs
  • 2006-11-13 Preload pictures for previous and next page to avoid flickering
  • 2006-11-13 Now it works again with PHP4 (PHP4 has an awful object model, far from anything standard)
  • 2006-11-12 Refactored thumb.php into classes; allow more than one gallery by defining multiple PageStores; general GroupHeader
  • 2006-11-11 Make it work with $EnableRelativePageVars=1
  • 2006-11-09 Update cache if the original picture changed; split it up into different files and classes. Ready for things like a Flickr connector
  • 2006-11-02 Send proper HTTP headers so that the browser caches pictures for an hour
  • 2006-11-01 Now compatible with PmWiki 2.2beta15
  • 2006-10-14 don't depend on mime_content_type (thanks to noe)
  • 2006-10-14 libgd2 support. Look at the $WikiGallery_ScaleMethod variable.
  • 2006-10-12 fixed several bugs with the title code from two days ago. Now title of paths with "." inside them work fine
  • 2006-10-10 add (:title ... :) line into overlay and picture pages, which includes the paths (so use proper paths in the picture directory and save the work to add proper title directives)
  • 2006-10-10 the current working path in shutdown functions is corrupted (at least in a Sarge install of PHP). So do a chdir to fix it
  • 2006-10-10 set {$GalleryOverview} correctly for pictures in the root of the pictures directory
  • 2006-10-08 thumbnail cleanup; internal thumbnails are default now
  • 2006-10-07 own thumbnail implementation
  • 2006-10-04 "go up" link added to go back to parent album list#
  • 2006-09-27 slideshow feature added


1. Get the latest WikiGallery version with git

 cd yourpmwiki/cookbook
 git clone git:// wikigallery

or download the snapshot: (zip)

2. Load the wikigallery into your PmWiki installation:

 $WikiLibDirs[] = new GalleryPageStore('Pics');

3. Create the cache directory (in the directory where your pmwiki.php is) and the same for the pictures directory. The former must be writable by the webserver (i.e. the user id the webserver is running under. The chmod in the following commands make sure that the webserver can write).

 cd the_dir_where_pmwiki_php_is
 mkdir cache
 mkdir pictures
 chmod 777 cache

4. Copy photos (possibly sorted in directories) into the pictures directory. Make sure that ImageMagick (especially the convert command) is installed on your server, or alternatively that your PHP supports libgd2. By default WikiGallery will try both.

That's it! Go to the Pics.HomePage page and see the available albums and pictures.

Trouble Shooting

  • If you don't see pictures/thumbnails, look into the HTML source code of the page and look for links with action=thumbnail, something like the following. Go directly to that URL with your browser. Often it will tell you directly what is wrong, e.g. wrong permission etc.


There are some new pages, templates and defaults:

Site.GalleryPictureTemplateThe template for a new picture page.
Only includes the default below.
Site.GalleryPictureDefaultThe default layout for picture pages.
Change this if you don't like the layout.
Site.GalleryOverviewTemplateThe template for a new album page.
Only includes the default below.
Site.GalleryOverviewDefaultThe default layout for album pages.
Change this if you don't like the layout.
Site.GalleryHomePageTemplateThe template for Pics.HomePage.
Only includes the default below.
Site.GalleryGroupHeaderDefault header. Only shows the {$Title}.
Site.GalleryHomePageDefaultThe default layout for Pics.HomePage
Site.GalleryListTemplatesPagelist templates for several things

The idea is that the templates only include the default pages. Every page of the gallery will look like the template until you modify it. Then it is statically stored in the wiki.d, i.e. not dynamically created anymore.

To customise the design, just change the default pages. Because the templates just include the defaults the changed design will take place everywhere, also in the already saved pages.

... and some virtual pages:

Assuming "Pics" is your gallery group:

Pics.HomePageA homepage for a gallery group showing the albums
and pictures in the root folder
Pics.Xmas2005IndexA wiki trail with the pictures of the album "Xmas 2005"
Pics.Xmas2005AlbumsA wiki trail with the subalbums of "Xmas 2005"
Pics.Xmas2005-XmasEve123The single picture page of "Xmas 2005/Xmas Eve 123.jpg"
Pics.Xmas2005-XmasEve123NavigationA trail with $WikiGallery_NavThumbnailColumns many
thumbnails of the pictures around "Xmas 2005/Xmas Eve 123.jpg" in the album

These kind of pages are automatically created, or more precisely only exist virtually depending on the files in your picture folder. If you modify a page of these they are not dynamic anymore, but become normal Wiki pages in your wiki.d folder.

The following page variables are added:

$GalleryAlbumthe path relative to the base path of the current album
It's set for every overview page, e.g. for Pics.Xmas2005 it will be set to "Pics/Xmas 2005"
$GalleryOverviewthe pagename of the overview page of the current picture,
e.g. "Pics.Xmas2005" for the picture "Pics.Xmas2005-XmasEve123"
$GalleryPicturethe path relative to the base path of the current picture
e.g. "Xmas 2005/Xmas Eve 123.jpg"
$GallerySizecurrent picture size (stored in the cookie "gallerysize";
can be changed as in http://bla/Pics/Foo-Bar?gallerysize=1024)
$GalleryNextname of the page of the next picture in the album (without the group)
$GalleryNextNextname of the page of the next after next picture in the album
(without the group)
$GalleryPrevname of the page of the previous picture in the album (without the group)
$GalleryPrevPrevname of the page of the previous before previous picture in the album
(without the group)
$GalleryNextPicturepath of the next picture in the album (without the group)
$GalleryNextNextPicturepath of the next after next picture in the album
(without the group)
$GalleryPrevPicturepath of the previous picture in the album (without the group)
$GalleryPrevPrevPicturepath of the previous before previous picture in the album
(without the group)

The following configuration options exist:

 # Paths
 SDV($WikiGallery_PicturesWebPath, "pictures/"); 
 // the path to the galleries (relative to the host url
 SDV($WikiGallery_PicturesBasePath, $WikiGallery_PicturesWebPath); 
 // the path to the galleries (on the filesystem, relative to pmwiki.php)
 SDV($WikiGallery_CacheWebPath, "cache/"); 
 // the path to the thumbnail cache (relative to the host url
 SDV($WikiGallery_CacheBasePath, $WikiGallery_CacheWebPath); 
 // the path to the thumbnail cache (on the filesystem, relative to pmwiki.php)
 SDV($WikiGallery_ImageMagickPath, "/usr/bin/"); 
 // absolute path to the ImageMagick binaries (mogrify, convert, ...)
 SDV($WikiGallery_FindPath, ""); 
 // path to the find command, usually /usr/bin/
 SDV($WikiGallery_PhpThumb, ... ); // the phpthumb script url
 # How the wiki pages look like
 SDV($WikiGallery_NavThumbnailColumns, 5); // odd number
 SDV($WikiGallery_SortByDate, FALSE ); // otherwise alphabetical
 SDV($WikiGallery_SortBackwards, FALSE );
 SDV($WikiGallery_AlbumsSortByDate, TRUE ); // otherwise alphabetical
 SDV($WikiGallery_AlbumsSortBackwards, TRUE );
 SDV($WikiGallery_DefaultSlideshowDelay, 5 );
 # Thumbnail generation
 SDV($WikiGallery_ScaleMethod, "auto");
 // either "auto", "imagemagick" or "libgd2"; "auto" means first imagemagick, then libgd2
 SDV($WikiGallery_HighQualityResize, true); 
 // use better quality (but slower) resize algorithms?
 SDV($WikiGallery_UseAuthorization, false); 
 // try to authorize for the page the picture/thumbnail is belonging to
 SDV($WikiGallery_UseFlatCache, true);
 // use flat cache filenames, because it's more compatible
 // If you have tons of pictures setting this to false could speed up
 // the gallery because then you don't get 1000s of cache files in one directory
  # Clean up of thumbnail cache
 SDV($WikiGallery_CleanupDelay, 7); 
 // if nobody accessed a thumbnail for a week, purge it
 SDV($WikiGallery_CleanupInterval, 3600); 
 // cleanup once an hour
 # Misc
 SDV($WikiGallery_PathDelimiter, "-" ); 
 // must be something valid in page names
 SDV($WikiGallery_DefaultSize, 640);


The following markup is added:

 (:gallerypicture group? width picture:)
 (:gallerypicture group? width?:height?!? picture:)
 (:gallerypicturerandom group? width album:)
 (:gallerypicturerandom group? width?:height? album:)
 (:gallerypicturepage picture:)

To include a thumbnail, write:

 (:gallerypicture 200 Xmas 2005/Xmas Eve 123.jpg:)

To include a random picture of an album, write:

 (:gallerypicturerandom 200 Xmas 2005:)

The 200 is the size of the longer side of the picture. If you want to put a picture into an arbitrary rectangle, use the w:h notation:

 (:gallerypicturerandom 200:150 Xmas 2005:)

In all three example the aspect ratio is not changed, i.e. the sizes are maximum size. To force another aspect ratio, the w:h! notation is used:

 (:gallerypicturerandom 200:20! Xmas 2005:)

The result is a 200 pixels wide picture which is only 20 pixels high.

The last example is about the (:gallerypicturepage ...:) markup. As described before, every picture get's a wiki page assigned (see in the Implementation section for details). To link to that page, do the following:

 [[Pics.(:gallerypicturepage Xmas 2005/IMG1234.jpg:)]]

To show a thumbnail linking to its page, do this:

 [[Pics.(:gallerypicturepage Xmas 2005/IMG1234.jpg:)|
   (:gallerypicture 100 Xmas 2005/IMG1234.jpg:)]]

Finally, to make a thumbnail which links to a full size version of the photo, which opens in another window:

 %newwin% [[(:gallerypicture 0 Xmas 2005/IMG1234.jpg:)|
 (:gallerypicture 100 Xmas 2005/IMG1234.jpg:)]]

Advanced customisation

More than one gallery group

It's possible to have more than one gallery group in a Wiki. For example you can add an "Uploads" group which includes all your uploaded pictures via the normal PmWiki upload mechanism:

 $WikiLibDirs[] = new GalleryPageStore(
               new GalleryDirectoryProvider(
                 "uploads/" ));
 $WikiLibDirs[] = new GalleryPageStore('Pics');

The gallery created at the end will be the default if you do not add the optional group parameter to the markup like here:

 (:gallerypicture Pics 200 Xmas 2005/Xmas Eve 123.jpg:)

Custom thumbs providers and phpThumb

The thumbnail generator can be changed by passing it as forth parameter to the GalleryDirectoryProvider constructor:

 $WikiLibDirs[] = new GalleryPageStore('Uploads',
                    new GalleryDirectoryProvider(
		      "Upload", "uploads/", "uploads/",
 		      new InternalThumbProvider(
 		        "Uploads", // the wiki group
 			"cache/",   // the cache base path
 			"cache/",   // the cache web path (only if you don't 
 				    // use authorisation for thumbnail, see
 				    // $WikiGallery_UseAuthorisation
 		        "uploads/", // the pictures base path
 			"uploads/", // the pictures web path (also only for
 				    // $WikiGallery_UseAuthorisation=0
 		        "auto"      // scale method, "auto" is default

Another example is the phpThumb generator:

 $WikiLibDirs[] = new GalleryPageStore('Uploads',
                    new GalleryDirectoryProvider(
		      "Upload", "uploads/", "uploads/",
		      new PhpThumbProvider( "Uploads" );


  • If you use BlogSimple2, maybe others as well: The $WikiLibDirs is set quite rudely by overwriting all changes. As WikiGallery depends on changes on this variable, make sure that WikiGallery is loaded later in your config.php.
  • If you want to have "private" albums which are not shown in any index, prefix them with a ".", e.g. call the directory ".Xmas 2005". You can still access them as usual, but they do not showup on the "*Albums" trail.
  • If you want more security (e.g. use the authorization of PmWiki also for the pictures), place your cache and pictures directories outside of the web server path and set the BasePath variables correctly (you can use absolute paths there). The current implementation checks the "read" authorization of the wiki page of the picture.
  • ImageMagick is the fastest if you want good quality. With WikiGallery_HighQualityResize=false the libgd2-scaler gives bad quality without any filtering.


WikiGallery implements a new PageStore to create pages on the fly. As soon as you edit the dynamic pages though, they will be stored inside of your wiki.d directory. Of course they do not change anymore then. So please do not edit the different dynamic trails (can pages be made readonly? That would help here...)

Path names of pictures and albums are mapped to Wiki pagenames in the following way:

 function fileNameToPageName( $filename ) {
   global $WikiGallery_PathDelimiter,$WikiGallery_ImgExts;
   $filename = preg_replace( '/'.$WikiGallery_ImgExts.'$/i', '', $filename );
   $filename = preg_replace( "/[^a-zA-Z0-9\\/]/", '', $filename );
   $filename = preg_replace( "/\\//", $WikiGallery_PathDelimiter, $filename );
   return $filename;

So extensions are removed and all characters other than normal letters and numbers are omitted. At the end every path delimiter / is replaced by -. Of course you have to make sure that this mapping is injective, i.e. no two pictures get the same pagename.


Please go to WikiGallery-Talk for the comments and discussion about WikiGallery.

Please only add comments to the WikiGallery-Talk page. Thanks Sts

See Also


User notes? : 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.