X-Gallery
<< X-Chat | Cookbook-V1 | X-Comment >>
Note: The recipes here are for PmWiki versions 0.6 and 1.0 only. For PmWiki 2.0 recipes, see Cookbook.
About
This is version 1.0 of X-Gallery (released June 22, 2004). This newest release has a lot of improvements over the previous beta release, like easier installation, automatic configuration for per-page or per-group attachments (user no longer needs to specify this), and severely improved thumbnail generation (sleeker, less code). I also added messaging so that users will know which images, thumbs, and image-pages have been added, as they are added. Several other enhancements like showing and hiding the upload button on the filmstrip view, etc etc. See documentation for more details.d
Important (Read this)
X-Gallery behaves differently depending on how you have configured file uploads. By default PmWiki is distributed with file-uploads disabled, so you will have to enable file uploads for this script to work properly. Also, by default PmWiki attaches uploaded files to the Group which the files were uploaded to. This works fine, but limits you to one Gallery/Album per Group. If you enable per-page attachments, it will then be possible to have more than one Album in a Group. As of version 1.0 X-Gallery will automatically detect which setup you have and function accordingly.
For more info, read the section below entitled Enabling Per-Page Attachments.
Features
- A WikiPage is created for each uploaded image - the image-page contains the image, comments and navigation which are defined by a template. There may be some users who don't like this idea, so let me explain my reasoning, and why I think it's better to have a WikiPage for each image: Images become searchable, either by name, or by keyword, RecentChanges page will record when the page was created, when users leave comments or make other changes it will also be recorded and finally, disk space is very cheap, the amount of space it takes up versus wasting cpu time dynamically generating content/images/pages is less expensive in my opinion. It just seems more in the spirit of Wiki to me.
- The user can easily customize the layout of the thumbnail index and image-pages. See the section entitled Customizing Layout below for more details.
- The script does it's best to try and handle wierd file names by a) creating a wiki page based on the file name, and b) rendering the image (with wierd characters) on the image page. If you find any glitches or limitations let me know, and I'll see if I can't fix it. I created a special Wikify function for this purpose which takes in a string, and outputs a valid WikiPageTitle.
- Since PmWiki doesn't allow page titles to begin with digits, XGallery needs to take some precautions to ensure that appropriate page-titles are generated from the uploaded image files. To solve this problem all page-titles are prepended with the keyword Image-, followed by a wikified version of the filename. Prepending all ImagePages with the keyword Image- helps to keep ImagePages separate from other pages in your wiki, so doing a search for images becomes very easy, you only need to search for the keyword Image-; a very convenient side-effect in my opinion.
Enabling Per-page Attachments
Assuming that you have enabled file uploads, the default behaviour for PmWiki when uploading files is to attach them to the current WikiGroup. This is fine, but uploading images to a group means you will only be able to have one Album per Gallery (one Album/Gallery per WikiGroup).
With Per-page attachments, uploaded files become attached to the current WikiPage, which means each Group becomes a Gallery, with multiple Albums (pages).
To enable per-page attachments, add the following line to your config.php file:
$UploadPrefixFmt = '/$PageName/';
Now all files that you upload will be attached to the WikiPage you upload them to, and not the WikiGroup. Note that this applies to all pages in your Wiki, not just X-Gallery pages.
Download
Optional Downloads
Installing
- Download
x-gallery.php.txt(rename it to x-gallery.php on your system). - Put the file in your local/scripts/ directory
- Add the following line to your
config.phpfile:
include_once('local/scripts/x-gallery.php');
Creating a Thumbnail Index
Type the [[x-gallery:]] directive on the WikiPage where you want the thumbnail index to appear and save it. Your Gallery probably doesn't contain any images yet, so you'll see a message indicating that the Gallery is empty.
 |  |
If you have per-page-attachments enabled, then you'll see a message like the one on the right where the Group.Page names are both present, indicating that images will be attached to the Album (Page) rather than the Group (Gallery).
Adding Images to the Gallery
Uploading images is done using the existing facilities of PmWiki. You can get to the upload screen by appending ?action=upload to the page-url, or by clicking on the upload link usually displayed in the empty-gallery message.
If you're the site administrator you can use your FTP program to bulk-upload images to your uploads folder. (The exact location would be uploads/Groupname or uploads/Groupname.Pagename/ if you have per-page-attachments enabled).
When you're done reload the thumbnail-index page, you'll see a report of what directory, thumbnails or image-pages have been created. This report is only show once, the next time the page is loaded or refreshed the report won't appear.
 |
Deleting Images
To delete an entire Gallery, just remove the [[x-gallery:]] directive from your "thumbnail index" page. That will prevent the thumbnails from being show/generated, and it will also prevent any more ImagePages from being created.
Note: This doesn't physically remove any images or thumbnails, it just doesn't display them anymore. At this time, only Admin can (manually) remove these files. This is the same restriction that you will find in PmWiki.
To delete a page, just delete it in the normal way (edit the page, delete it's contents, then enter the single keyword "delete" at the top of the page, then save it).
Note: When you view the "thumbnail index", the page will be re-created. This might be useful if you are experimenting with different page layouts in the script and you want to re-create the page with a new layout. Also note that any comment on the page will be lost.
As far as I know, PmWiki doesn't currently have any way to delete files/images, so I'm not planning to implement such a feature in the Gallery. I hope to see some better administrative control of WikiPages in the future, as well as some basic file managment for file attachments.
Changing the Image-Page Layout
You can easily change the layout of the ImagePages that X-Gallery generates. There is a single variable called $xGalleryVars['output_template'] in the script file under the function named: xGallery_Init(). The default template looks something like this:
$xGalleryVars['output_template'] = '{{[[$Groupspaced]]}} / {{$Album}}
[[notitle]]
||table width=100%
|| %border=3%$image_url ||
|| [+[[$Titlespaced]]+] ||
[[x-comment:]]';
As you can see, it's just simple WikiMarkup augmented by a few local variables. $Album is just another name for "Page name of the thumbnail index", and $Gallery is just another name for $Group. In the above example, I've tried to be clever by changing the title of the WikiPage to the name of the Group/ThumbnailPage instead of Group/Imagename. I achieved this by using the [[notitle]] directive, and then manually adding the title, complete with {{Freelink}} markup to mimic the appearance of a regular WikiPage. Then under the image, I have inserted the actual page name (the title of the image), but in a smaller font, so the title (of the image/page) appears under the image instead of at the top of the page where it would normally appear. Lastly, I have used a separate add-on which I designed specifically for the X-Gallery, but which can stand on it's own, called X-Comment?. It's a simple script to allow users to add comments to the bottom of their script. If you don't want to allow user to add comments, then simply remove the [[x-comment:]] syntax from the output template.
If you need some help designing a slighly more elaborate template drop me a line and I'll be happy to help.
Your Comments
I'd like to hear any comments about this script, likes, dislikes, wishlist, suggestions, and bug-reports. You can email me directly (preferred), or you can post your comments here. Thanks.
Limitations
- Currently, only .jpg and .JPG images are supported. This is more of a choice than a limitation at the moment. Since most photo gallery's consist of photo's (actual photographs as opposed to diagrams, or other graphics), this means that 99% of the time, JPEG will be the format of choice.
- No support for .GIF (yet). This script uses the GD2 graphics library, and as such, is limited in that regard. With specific regards to .GIF, the copyright is due to expire in Summer 2004, and at that time the GD2 library might incorporate the .GIF algorithms; if that happens, then I'll probably update the script to handle .GIF's as well.
- PNG is not supported simply because I personally don't use it, nor do I have any need for it. If there is a huge demand for it, then I guess I can add it easily enough.
- There's not much in the way of administering the Images in the Gallery, but this is somewhat deliberate. The script tries as much as possible to work within the boundaries of PmWiki. Since PmWiki doesn't offer much in the way of content administration, nor does this script. If/when advanced content management features become available within PmWiki, then I'll try and incorporate them in the Gallery as well.
Future Features I am Contemplating
- I am working on a future version that will support $Previous and $Next variables which will be links to other images in the Gallery, but I haven't quite decided how I want this to work yet.
Copyright
See PmWiki distribution.
Your Comments / Suggestions
I'd like to hear any comments about this script, likes, dislikes, wishlist, suggestions, and bug-reports. You can email me directly (preferred), or you can post your comments here. Thanks.
- Are there any examples? (Stefan Jahn)
- Sorry, I don't have the resource to set up an off-site demo. I tried to provide detailed description and screen shots to give users a good feel for how it works. If you require more, then you'll have to download, install and try it out for yourself.
- It's a great gallery. I was wondering if there is some space under each thumbnail picture for two to three words specification in the future version. --fangz
- Anything's possible. Can you provide more details or example of what you would do with "two to three words"? Are you thinking of a description of some sort? Statistics? etc? Probably best to email me directly. You'll find my email address in the comment's of the script code.
- Agreed! Very nice gallery! I particularly like that it works within the assumptions of PmWiki. As such, it seems that the $Previous $Next stuff would work well as a sort of modified Trail that used the gallery index as its Trail Page. --nokes
- Would be nice if it supports the
$UploadUrlFmtset in theconfig.phpfor special upload directories (useful for e.g. Farms) --Klonk - I never got it working in the actual PMwiki version (September 2006) - Andreas Mascheck
pmwiki-2.3.32 -- Last modified by {{}}?