• View
• Edit
• History
• Attach
• Print
• Backlinks

WikiGallery

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?

Description

Concept

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

Installation

1. Get the latest WikiGallery version with git

 cd yourpmwiki/cookbook
 git clone git://github.com/sttts/wikigallery.git wikigallery

or download the snapshot:

 http://1stein.org/download/wikigallery.tar (zip)

2. Load the wikigallery into your PmWiki installation:

 include_once("$FarmD/cookbook/wikigallery/wikigallery.php");
 $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.

 http://1stein.org/Pics/Abc-bla?action=thumbnail&group=Pics&image=Abc%2Fbla.png

Customisation

There are some new pages, templates and defaults:

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:

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:

The following configuration options exist:

 # Paths
 SDV($WikiGallery_PicturesWebPath, "pictures/"); 
 // the path to the galleries (relative to the host url http://foo.com/)
 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 http://foo.com/)
 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);

Markup

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:

 include_once("$FarmD/cookbook/wikigallery/wikigallery.php");
 $WikiLibDirs[] = new GalleryPageStore(
                    'Uploads',
               new GalleryDirectoryProvider(
                 "Upload",
                 "uploads/",
                 "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" );

Notes

• 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.

Implementation

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.

Comments

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

• See http://1stein.org/Pics/2006MuenchenFussballgegenAnalysis as an example gallery
• http://phpthumb.sourceforge.net/
• WebSvn

Contributors

• sts