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

YAG

Questions answered by this recipe

Q: I have a large number of images in a folder, for which I need to create a thumbnail gallery. Since the number of images is large, I would like the gallery to be distributed over multiple pages. Is there a recipe that will do that for me?

A: Yes, YAG exactly does that. It is designed for creating large thumbnail galleries distributed over multiple pages. It is easy to use and can be customized with many features. You can include multiple images using range syntaxes in a single line, as well as use wildcards for searching a local folder and displaying multiple images from it. In addition, for a gallery you can mention a 'base URL' for the location of the images, thus avoiding the task of writing long URLs multiple times for every image. Display options include linking thumbnails to original images, or displaying the original images in a container in the gallery itself.

Description

YAG (Yet Another Gallery tool) for PmWiki enables creation of thumbnail galleries from a list of images. The gallery can be display over multiple pages. The thumbnails are created using the 'convert' utility and are cached in a cache folder. It comes with quite a few options, for example in a gallery it lets one mention a 'base URL' for the location of the images, thus relieving the task of writing long URLs (or paths) multiple times for every image. The images can be located in the upload folder of PmWiki (attachment with the same or different page), some other local folder (e.g. pub folder), as well as they can be located externally (images from the WWW). Multiple images (range of images with similar names) can be included using range/wildcard syntaxes. Multiple images from local folders can be included using the '*' wildcard. Display options include linking thumbnails to original images, or displaying the original images in a container in the same page as the gallery. One can use simple custom PHP functions for generating HTML for the gallery..

Δ A gallery with multiple pages Δ A gallery with a 'div' container Δ Hovering on an image displays caption (can be customized for different behavior) Δ A gallery with style='nohead,nofoot,rightcaption' option displaying detailed caption on the right of thumbnails

Demonstrations Live Demonstrations: For live demonstrations visit http://fling.seas.upenn.edu/~subhrabh/cgi-bin/wiki/index.php?n=Media.ArtPhotography-PhotoArt http://fling.seas.upenn.edu/~subhrabh/cgi-bin/wiki/index.php?n=Projects.ITPmWiki-YAGAGalleryTool http://fling.seas.upenn.edu/~subhrabh/cgi-bin/wiki/index.php?n=Media.ArtDigitalArt-Blender3DModelling (uses the new style option introduced in v1.9] https://alliance.seas.upenn.edu/~paatrn/wiki/index.php?n=Main.HomePage (uses a custom PHP handler function introduced in v2.0) https://alliance.seas.upenn.edu/~graspk12/wiki/index.php?n=Main.Photos     Installation Installing YAG is as simple as it can get: Download the attached YetAnotherGallery.phpΔ(check file consistency) file and place it in the cookbook/ folder. For the newer version download YetAnotherGallery2.phpΔ You will probably want to save the file as "YetAnotherGallery.php", i.e. omit the "2" and generally follow the rest of the instructions. In /local/config.php add the line include_once('cookbook/YetAnotherGallery.php'); In YetAnotherGallery2.php, on line 43, is a hard-coded local address reference: "$AlansPubDirUrl='http://'.$_SERVER['HTTP_HOST'].'/wiki/pub';". You may need to change this to suit your installation. YetAnotherGallery expects local pictures to be in the directory .../wiki/pub/ or a further subdirectory. Dependencies: convert : This utility is a part of the ImageMagick package. It is used to create the thumbnails and store the smaller images in the cache. To check if the utility is installed, just type 'convert' in a terminal. Ubuntu Linux hosts can simply install the 'imagemagick' package for installing the utility. Upgrading to v1.9: If you had created a custom container type or redefined any of the '$YetAnotherGallery->' PHP variables in config.php for YAG v1.8 or earlier, you may need to update them. Refer to the PHP variables section for details.     Use Syntax: YAG [ option1=o1, option2=o2, ... ] { url_or_path | caption && url_or_path | caption && ... }     Features: One can mention the maximum number of thumbnails to display per page (number of rows and columns) of the gallery by setting the 'cols' and 'maxrows' options. Multiple pages are created automatically based on that. The thumbnails can be made to link to the original images (either open in a pop-up or in the same window) or can be made to display the original images in a container in the same page as the thumbnail gallery (see the 'container' markup option). 'url_or_path' can be local attachments (e.g. Attach:file.jpg or Attach:Group.Page/file.bmp) or URL from the web (e.g. http://mysite.com/image.png) or a local path (e.g. pub/skins/coolskin/images/banner.jpg). It is possible to specify a range of URLs in a single line. (e.g. files IMG_001.jpg, IMG_002.jpg, IMG_003.jpg, ..., IMG_120.jpg can be included in a single line by using IMG_[%03d<<range:1,120].jpg for the 'url_or_path') For local images (attachments using Attach: prefix or local paths), wild-card based directory search is also allowed (e.g. pub/skins/coolskin/images/[*.*] to include all images under the folder pub/skins/coolskin/images/, or Attach:*.jpg to include all JPG images in the upload folder of the current page). The caption can contain simple HTML tags or wiki markups, as well as backreference from the url/path. One can specify a Base URL ('urlbase' option) for all (or some of) the images in a gallery. One can have multiple different galleries in the same page by using the "name" option. See Markup options and URL format & ranging for details on the available options and URL formattings.

Examples:

1. The basic use of 'urlbase' option:

   YAG [ urlbase = "http://www.sitewithprettyimages.net/files/images/" , cols=3, maxrows=5]
   {
      IMG_001.jpg | The caption \n can be split \n into multiple lines &&
      IMG_002.jpg | Another caption &&
      -- http://www.anothersite.com/images/IMAGE_01.png |
                     This does not use <b>'urlbase'</b> due to the preceding "--"
   }

2. One can use images from local attachments, local paths as well as images from WWW. Whitespaces do not matter.

   YAG[style='div,nofoot', containerheight=300]
   {  http://upload.wikimedia.org/wikipedia/en/c/ca/Pmwiki-32.png | PmWiki logo from Wikipedia &&
      Attach:file.jpg | Uploaded image  &&  Attach:Group.Page/file2.jpg | Uploaded image from a different group 
      pub/publicimages/photo.jpg | This is a photo from the pub folder. }

3. URL range - the following creates gallery using images fracday0.gif, fracday1.gif, ..., fracday9.gif from http://sprott.physics.wisc.edu/fractals/:

   YAG [urlbase="http://sprott.physics.wisc.edu/fractals/",name="frac",cols=4,maxrows=1,container='self']
      { fracday[%d<<range:0,9].gif | Fractal number [*] }

4. Search local folder - the following creates gallery using all images under the folder pub/publicimages/ (relative to pmwiki's root folder):

   YAG [name="pubphotos",cols=5,maxrows=3]
      { pub/publicimages/[*].jpg | Photo file [*] }

5. Specify local folder (December 2104 version) - the following creates a gallery using the images specified. This is the only method I (Engineeral) have tested:

   YAG [name="SomeDumbDirectory",cols=5,maxrows=5,refreshcache=yes]

  /home/SomeDumbUser/www/wiki/pub/SomeDumbDirectory/filename02.jpg | caption for filename02.jpg
  /home/SomeDumbUser/www/wiki/pub/SomeDumbDirectory/filename03.jpg | caption for filename03.jpg
     "etc."

Note: 'container' option has been superseded by 'style' option since v1.9. 'container' option is, however, still supported. See below for details.

Markup options

The following options can be used with the markup for any gallery.

URL/path format, range declaration, glob pattern and backreferences

An 'url_or_path' can contain a range or list for including multiple files in a single line. Alternatively it can contain a wildcard to search a local folder to include multiple images in it. Below is a brief description of the syntax of 'url_or_path' and 'caption'

url_or_path:

• General format of 'url_or_path': path/to/file.ext.
• 'urlbase', if defined in the options, will get appended to the beginning of each declared URL/path when the final URL is formed (or path is looked up). However individual URLs/paths can be exempted from this rule by preceding them with "--" (without the quotes).
• 'url_or_path' can contain a single sequence of wildcard enclosed in [...]: e.g., path/to/multiple[WildcardString]folders/or/files.ext, where,

First type of WildcardString:

• IMG_[%03d<<range:1,998].png will include all the images from IMG_001.png to IMG_998.png.
• FILE[%s<<range:a,f].jpg will include all the images FILEa.jpg, FILEb.jpg, ... , FILEf.jpg.
• SameName.[%s<<list:png,gif,jpg] will include the images SameName.png, SameName.gif and SameName.jpg.
• IMG_[%d<<range:1,9,2].png will include the images IMG_1.png, IMG_3.png, IMG_5.png, IMG_7.png and IMG_9.png (i.e. 1 to 9, but with increment/step of 2).
• Folder[%d<<range:1,3;list:7,9,13;range:20,24,2]/file.png will include images Folder1/file.png, Folder2/file.png, Folder3/file.png, Folder7/file.png, Folder9/file.png, Folder13/file.png, Folder20/file.png, Folder22/file.png, and Folder24/file.png in that sequence.

Second type of WildcardString:

• pub/images/[*/*].png will search for all PNG files inside pub/images/ folder and its subfolders, and include them in the gallery.
• Attach:[*.png] will search the upload folder corresponding to the current page for all PNG files, and include them.

caption:

• Can contain '\n' to indicate line break as well as the basic HTML formatting tags like '<i>', '<font>', etc.
• Can contain [*] that is substituted by a simple backreference from url_or_path's [...] block (described above).

1.

  YAG [ urlbase="http://", name="myimages", cols=4, maxrows=1, style='div']
     { 
       www.mysite.com/IMG_[%d<<range:0,9].jpg | This is image number [*] &&
       www.anothersite.com/anotherImage.bmp | Another image &&
       -- Attach:localImage.gif | This is an attachment image and is not to be started with "http://"  }

is equivalent to writing

  YAG [ urlbase="http://", name="myimages", cols=4, maxrows=1, style='div']
     { www.mysite.com/IMG_0.jpg | This is image number 0 &&
       www.mysite.com/IMG_1.jpg | This is image number 1 &&
       www.mysite.com/IMG_2.jpg | This is image number 2 &&
       www.mysite.com/IMG_3.jpg | This is image number 3 &&
       www.mysite.com/IMG_4.jpg | This is image number 4 &&
       www.mysite.com/IMG_5.jpg | This is image number 5 &&
       www.mysite.com/IMG_6.jpg | This is image number 6 &&
       www.mysite.com/IMG_7.jpg | This is image number 7 &&
       www.mysite.com/IMG_8.jpg | This is image number 8 &&
       www.mysite.com/IMG_9.jpg | This is image number 9 &&
       www.anothersite.com/anotherImage.bmp | Another image &&
       -- Attach:localImage.gif | This is an attachment image and is not to be started with "http://" }

2.

  YAG [ urlbase="http://", style='lfloat']
     { www.mysite.com/IMG_[%d<<range:0,11].jpg |
                     This is [%s<< image num *3; list: my photo, Bob's photo, Nancy's photo; .2 unknown; *th image]
     }

is equivalent to writing

  YAG [ container='lfloat' ]
     { http://www.mysite.com/IMG_0.jpg | This is image num 0 &&
       http://www.mysite.com/IMG_1.jpg | This is image num 1 &&
       http://www.mysite.com/IMG_2.jpg | This is image num 2 &&
       http://www.mysite.com/IMG_3.jpg | This is my photo &&
       http://www.mysite.com/IMG_4.jpg | This is Bob's photo &&
       http://www.mysite.com/IMG_5.jpg | This is Nancy's photo &&
       http://www.mysite.com/IMG_6.jpg | This is unknown &&
       http://www.mysite.com/IMG_7.jpg | This is unknown &&
       http://www.mysite.com/IMG_8.jpg | This is 8th image &&
       http://www.mysite.com/IMG_9.jpg | This is 9th image &&
       http://www.mysite.com/IMG_10.jpg | This is 10th image &&
       http://www.mysite.com/IMG_11.jpg | This is 11th image
     }

3.

  YAG [ urlbase="Attach:", name='searchedImgs' ]
     { img[*].jpg | This is image [*] }

assuming that the upload folder of the current page contains the JPG image files imgBob.jpg, imgNancy.jpg, Harry.jpg, imgTom.jpg, img_001.jpg, Img002.jpg, the above is equivalent to writing

  YAG [ name='searchedImgs' ]
     { 
       Attach:imgBob.jpg | This is image Bob &&
       Attach:imgNancy.jpg | This is image Nancy &&
       Attach:imgTom.jpg | This is image Tom &&
       Attach:img_001.jpg | This is image _001 
     } 

Note: The 'url_or_path' and 'caption' themselves cannot contain the character '}', and the character sequence '&&'. The 'url_or_path' cannot contain the character '|'. And, the contents inside the placeholder @[...]@ in 'url_or_path' or 'caption' themselves cannot contain the characters ']', ';', ',' and the sequence '<<'. Use hex encoding for special characters in 'url_or_path', and HTML special character encoding for those in the 'caption'.

If you intend to make basic use of YAG you may want to skip to the Troubleshoot & FAQs section.

PHP variables

The following PHP variables can be set in config.php:

Troubleshoot & FAQs

Q: The thumbnails are not being displayed.

Q: I changes the values of 'cols' and 'maxrows'. The gallery is now looking weird (thumbnails overlap on each other, or are not of the right size).

Q: I updated an image, but the old thumbnail is still showing.
Q: I changes the values of 'imgmaxwidth' and 'imgmaxheight'. But the size of the thumbnails has not changed!
Q: How do I clear the cache?

Tip: When you are designing a gallery (i.e. have not finalized the number of columns/rows or the size of the thumbnails and are playing around with those options), always have refreshcache = yes set. This will ensure that the thumbnails are recreated with the changes you make.

Q: An URL I need to use has the characters '[', ']' or '&&'. These conflict with the syntax. What can I do?

Q: It seems YAG can fetch and display images from domain/site outside my wiki, but not the ones from folders in my wiki.

Q: I see the same thumbnail for two different images!! What's going on?

Release notes

See also

• Mini
• ThumbList
• AutoThumber
• Galleria

Contributors

• Subhrajit -- author

Comments

Please use the YAG-Talk page for comments and discussions.