pmGallery

Summary: Display your Picasa and Google Photo albums and pictures within PmWiki.
Version: 0.3.3 (25-Feb-2016)
Prerequisites: PHP5
Maintainer: DaveG
Categories: Images, Gallery, Picasa, Flickr, PHP55
Discussion: PmGallery-Talk
Download: ZIP or TAR
Users: +1 (View / Edit)

Summary

pmGallery can be used to display albums, thumbnails, and images direct from image stores like Picasa (Flickr coming soon), inside PmWiki pages. No images or thumbnails are stored locally, so there apart from uploading to Picasa there's no extra work involved in displaying your images within your wiki.

19-Jul-08: pmGallery requires PHP5. If you're using PHP4 you will see errors, not images.

Table of contents

Description

Uses a PmWiki markup to embed Picasa albums and images on a PmWiki page. Provides integration with Galleria.

Features

  • Display album covers clickable to the images within the album
  • Display thumbnail images, clickable to larger images
  • Display the contents of one or more albums on a single wiki page
  • Can automatically create 'virtual' wiki pages. This means you can display an entire album, and it's images with a single (:pmgallery:) directive!
  • Display random images from one or more albums
  • Automatic caching of feed files -- images are never stored locally, always retrieved from Picasa/Flickr
  • Display images from public and private albums
  • Make full use of your Picasa/Flickr tags
  • Full integration with Galleria, means stylish image presentation!
  • Future: display additional data, like Exif, comments, etc.

Demo

Basic demo is over at solidgone.org. Demo will be added here when things stablize.

Being used at...

If you're using pmGallery, feel free to add your site to this list. Let others see what pmGallery can do!

CRUX PPC Gallery

Installation

To install:

  • Download either the ZIP or TAR and extract the files and directory into your cookbook directory. Everything should be inside a folder cookbook/pmgallery. After extracting the files you should have the structure below. Make sure the cache directory is created:
   cookbook/pmgallery/
      |- pmgallery.php
      |- feeder.php
      |- picasa.php5
      |
      |- /wikilib.d/
      |      |- pmGallery.GroupFooter
      |
      |- /cache/
             |- <empty>     
  • Add these lines to your config.php:
    • changing "+VirtualGroup1" to the name of the PmWiki group in which your album will be placed. This is the same group as the page containing your (:pmgallery:) markup directive. Do not remove the "+" sign -- it's used to ensure automatic creation of a group footer.
    • changing "nickname" to your Picasa nickname
$pmGallery['virtualgroups'] = array('+VirtualGroup1');
$pmGallery['user'] = 'nickname';
include_once("$FarmD/cookbook/pmgallery/pmgallery.php");
  • Create the page VirtualGroup1/VirtualGroup1 and include these lines:

(:pmgallery album="MyAlbum":)

Options

Page not Found

pmGallery makes heavy use of 'virtual pages', which do not really exist within the wiki. If you are making use of these virtual pages to display albums and images, then you'll need to prevent PmWiki from displaying the usual 'page not found' error message":

The page "Unphotographed.Quiddity" doesn't exist. (Create Unphotographed.Quiddity)

By pre-defining these 'virtual groups' pmGallery suppresses the 'page not found' message for all pages within that group. Other groups will still show the message as usual. Add this to your config.php before the include_once line:

$pmGallery['virtualgroups'] = array('VirtualGroup1','VirtualGroup2');

Auto-Create GroupFooter

pmGallery will automatically create a Group.GroupFooter page for you if you include a "+" in front of the group name on the virtual path setting:

$pmGallery['virtualgroups'] = array('+VirtualGroup1','VirtualGroup2');

After the GroupFooter is created you can edit it, and change and format it as you require. The initial content of the GroupFooter is:

(:pmgallery:)
(:div id="pmGallery_Image":)
(:divend:)

The key (:pmgallery:) directive is there to actually generate the album or images. The "pmGallery_Image" DIV is there for Galleria integration.

Parameters

All parameters below can either set parameters in your config.php, where you know they will apply site wide, or at each (:pmgallery:) directive. Parameters supplied in config.php will be over-ridden if also supplied within the directive.

The only parameter you really must set is user. But in order to enjoy the automatic generation of albums, you'll also need to either create or have pmGallery auto-generated them for you.

  • In order to set parameters in config.php use this format:
   $pmGallery['parameter_name'] = 'value';
  • In order to set parameters with the markup directive use this format -- note that quotes are optional, but must be used if the value contains spaces.
   (:pmgallery parameter_name="value" :) 

These parameters are typically used within the markup directive:

  • album: The name of the album -- you can see this at the end of the URL on Picasa public albums. For example picasaweb.google.com/nepherim/NewYork2007, the album name is NewYork2007. If album is supplied, then show images in the album; if album is blank then show a list of albums. You can provide more than one album name, separated with a comma:
  (:pmgallery album="NewYork2007,Quiddity":)
  • wikitarget: Specifies the group or page to load images into when the user clicks. Usually left blank, in which case the current group will be used, with the name of the image being used as the page name. Otherwise for albums specify the wiki group; for pages specify the group .page.
  • tag: Used to search for images with matching tags.
  • random: Number of random images to include. If more than one album is provided, images will be selected randomly across albums.
  • startimg: Specified the image to start displaying. Used if paging across many images, in conjunction with 'maxresults'.
  • width: Override for image display; usually set in CSS rather than as a parameter.
  • height: Override for image display; usually set in CSS rather than as a parameter.
  • query: Searches for this text across descriptions and tags. Also use this to work around Googles API bug which prevents getting results in date order. Used for RSS recent changes type feeds.

Usually in markup directive

These parameters usually set in config.php, but may sometimes in the markup directive:

  • user: With Picasa this is the username or nickname that you login with, ie, "nepherim".
  • thumbsize: Default is 72. Other options are: 32, 48, 64, 72, 144, 160,200, 288, 320, 400, 512, 576, 640, 720, 800
  • imagesize: Default is 640. Other options are: 32, 48, 64, 72, 144, 160,200, 288, 320, 400, 512, 576, 640, 720, 800
  • maxresults: Maximum number of images or albums to display on a single page. Default is 50.
  • wrapper: A '>' separated string defining the format for outer and inner html tags. The outer tag surrounds all image/albums being displayed. The inner tag surrounds each image or album. Default is 'div'. Examples: 'ul > li', 'div > div', 'div', 'span', etc
  • mode: Determines how pmGallery will operate.
    • 'cover': shows the cover of the album(s) specified.
    • 'linkdirect': links direct to source image, rather than embedding the image within a wiki page. Usually used with external plugins (like Galleria that need the full image URL to do their magic.
  • provider: Where the images are coming from: "picasa". Default is "picasa"

Usually site-wide

These parameters are usually set globally in config.php, like this:

$pmGallery['user'] = 'nepherim';
  • urlbase: Country code of the source of the RSS feed, ie, "de", "fr", "co.uk", etc. Default is "com"
  • proxy: specify the proxy and port ('proxy.server.com:8080')
  • authkey: Used to display private albums and images. Each key is specific to the domain on which your wiki resides. You'll need to get either a Picasa API key, or a Flickr API key. Not yet fully supported -- I'm not clear how Picasa manages authkeys.
  • cachedir: Location of the cache directory. Default is [directory of this file].'/cache'. NO trailing /
  • cachelife: Determines how long cache entries remain. Entries are automatically deleted after this period. Set to '0' to disable the cache. Default is '7200' (2 hours).

Not usually used

These parameters are not typically set by the user:

  • debug: Set to true (not quoted), to send debugging output to the web server log. Default is false.
  • imageurl: Usually set automatically, and does not need to be set by user.

Examples

In all the examples below, you only need to provide the parameters within the markup if they are not already in config.php, or if you want to override the values in config.php.

RSS Style, recent images

A bug in Googles API prevents a true implementation, but you can fake things out by using the query parameter:

(:pmgallery user=nickname tag="tag_list" maxresults=15:)

Automatically generate virtual albums

pmGallery can automatically generate a thumbnail list of clickable album covers, linking to clickable image thumbnails, and onto a large version of the image. You only need to include the markup directive on a single page. No other pages need to be created! Add this directive to any page, replacing 'nickname' with your actual nickname:

(:pmgallery user=nickname :)

And then either create or have pmGallery auto-generate the footer for you. Change "groupname" to the name of the PmWiki group in which you want to auto-generate the album:

$pmGallery['virtualgroups'] = array('+groupname1');

Include images from multiple albums

(:pmgallery user=nickname albums="album1,album2" :)

Include a random number of images from multiple albums

(:pmgallery user=nickname albums="album1,album2" random=5 :)

A single random image in a sidebar

Include a single random images based on a list of tagged images, with the link pointing to the image. This example is great for using in the sidebar.

(:pmgallery user=nickname tag="mytag" random=1 thumbsize=144 mode=linkdirect wrapper="div > div":)

Generate a numbered list albums

(:pmgallery user=nickname wrapper="ul>li" :)

Present images in a different wiki group from albums

Place the markup directive on a page in groupA, and have the images appear on pages in group groupB:

(:pmgallery user=nickname wikitarget="groupB" :)

Display large thumbnails

(:pmgallery user=nickname thumbsize=160 :)

Styling

If you're using PmGallery across a range of skins, you can use inline style definitions rather than changing each skin. Add something like this to your config.php file, changing the styling to suit:

$HTMLStylesFmt['pmgallery'] = '.pmGalleryWrapper {text-align: center}';

More coming later... (outer and inner classes)

Notes

Cache empty Virtual pages: Auto creation of GroupFooter

Galleria

The automatically generated GroupFooter includes a DIV used by Galleria.

(:pmgallery:)
(:div id="pmGallery_Image":)
(:divend:)

FAQ

Error Messages

Error message like the one below are usually caused by passing a bad parameter, or bad value to a parameter. Check that you have used one of the valid thumb/image sizes for example. Often copying the URL in the message into your browser will show the error that Google reports, to help you narrow down what the issue might be.

Warning: file_get_contents(http://picasaweb.google.com/data/feed/api/user/nepherim?kind=photo&max-results=50&start-index=1&thumbsize=142&q=&tag=unphotographed) [function.file-get-contents]: failed to open stream: HTTP request failed! HTTP/1.0 500 Internal Server Error in /home/nepherim/apps/pmwiki-2.2.0/cookbook/pmgallery/feeder.php on line 51

Bugs and Suggestions

  • new: Provide ability for album thumbs to be local images. (Requested by SteP, Peter Bowers)
  • new: Provide Flickr support: create a Flickr API.
  • new: Provide an API to pull images from local storage via a Picasa XML export file. (ref Klaus Hempelmann, and Mediawiki Picasa XML export plugin).
  • new: Use templates to provide advanced layout support.
  • new: Retrieve images by photoid, rather than using full url.
  • new: Allow exclusion of albums.
  • bug: Cannot return EXIF data when querying by tags. Please vote for a resolution to this bug on the Picasa API bug tracker.
  • bug: Thumbnail images are sometimes mis-aligned vertically (top margin is being set incorrectly).

Change log / Release notes

0.3.3 (25-Feb-2016)

  • chg: PHP 5.5 compatible.
  • bug: Only use 'q' parameter is it is not empty.

0.3.2 (12-May-11)

Contributors: SteP, DaveG

  • bug: Ensure cache directory exists in Git. (Reported by SteP)

0.3.1 (1-Jun-09)

  • bug: file_get_contents failed to open stream. Query parameter not allowed for album kinds. (Reported by SteP)

0.3.0 (12-Mar-09)

Contributors: DaveG, cda

  • new: Add support for query parameter (allows RSS style feed, as Picasa sorts desc if q= parameter exists).
  • new: Allow option of showing a random image when there is no album provided (for instance when when a tag is provided).
  • fix: Prevent error if unable to retrieve feed -- write to webserver log.

0.2.0 (21-Dec-08)

Contributors: DaveG

  • new: Added GroupFooter.
  • new: Ignore parameters that have values like "{$$xxxx}"; allows use in (:include:).
  • chg: Added ability to return EXIF data.

0.1.4 (29-Jul-08)

Contributors: DaveG

  • bug: Problem decoding > under RTF8 (identified by Damhaug).

0.1.3 (19-Jul-08)

Contributors: DaveG

  • bug: corrected url construct (first parameter had '&' not '?'

0.1.0 (17-Jul-08)

Contributors: DaveG

  • First beta release.

Comments

See Discussion at PmGallery-Talk.

See Also

  • Galleria: pmGallery provides full integration with the Galleria image viewer.

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