Gallery2:Lightbox JS Tutorial - Gallery Codex
Personal tools

Gallery2:Lightbox JS Tutorial

From Gallery Codex

Notes worth mentioning before we begin

This tutorial covers a minimal installation of Lightbox JS 2.0.2 onto a Gallery2.1.2 site. As far as I know, this modification is theme-independent; you can insert it into any theme and get going.

Sadly, I'm not a programmer and not capable of providing any meaningful support -- this is just my notes on my installation of Lightbox JS, which I wanted to share in the hopes of saving other users some time and effort.

There are at least two known themes that have lightbox built in. They are PGlightbox and Greypop

This tutorial includes URLs that you'll need to customize for your installation. I have started urls with /[path]/[to]/ -- you need to replace that with your own urls.

Like most computer weenies, I do all of my text-editing work on my computer, and then use FTP to upload my files to the server. These instructions are designed for working that way; if you edit directly on the server, I bow to your superior computer prowess, and you'll have to adapt these instructions to fit your method.

The tutorial proper

Download Lightbox JS from http://www.huddletogether.com/projects/lightbox2/#download , unzip it, and open the lightbox folder.

In the lightbox folder, go to the js folder and open "lightbox.js" in the text editor of your choice.

replace lines 62 and 63 with the following lines, which sets the image paths. Change the image paths that I've written as necessary to refer to your installation of Gallery2 on your website.

/* customized URLs for this installation of Lightbox JS */
var fileLoadingImage = "/[path]/[to]/lightbox/images/loading.gif";		
var fileBottomNavCloseImage = "/[path]/[to]/lightbox/images/closelabel.gif";
/* end customized URLs for this installation of Lightbox JS */

Around line 426, you'll see a line that says this.preloadNeighborImages();. Immediately after this line, and before the line },", add the following line. This addition eliminates a flashing-cursor problem that occurs in Firefox (my guess is that future versions of Lightbox JS won't need this mod, so check which version you have before doing this).

if (!document.all) document.getElementById('prevLink').focus(); // modification added to fix Firefox flashing-cursor problem

Close lightbox.js, you're done with it. Upload the entire lightbox file folder to the top folder of Gallery2 on your website.

Now, you'll need to edit three files (at least) in your theme folder. So, download the folder for your theme (at a minimum, download the "theme.inc", "templates/local/theme.tpl" and "templates/local/album.tpl" files.).

Edit the "theme.inc" file for the Gallery2 theme(s) you are using. You'll need to ADD these lines of text to the file, after the line that says $theme['columnWidthPct'] = floor(100 / $params['columns']);:

				/* Add resizedId to child values, required for Lightbox JS */
				if ( $theme['children'] ){
				    foreach ( $theme['children'] as $key => $value ){
				        if ( $value['id'] ){
				            list($ret,$resizedIds) =  
                            	GalleryCoreApi::fetchResizesByItemIds(array($value['id']));
				            if ($ret)
				                return $ret;
				        }
				        $theme['children'][$key]['resizedId'] = $value['id'];
				        if ( $resizedIds ){
				            /* Find the best resized option
				             * 
				             * Use width/height max=800; */
				            $lboxMaxEdge = 800;
				            $resizedEdge = NULL;
				            $resizedId = NULL;
				            foreach ( $resizedIds[$value['id']] as $resize ){
						$width = $resize->getWidth();
				                $height = $resize->getHeight();
				                $edge = ( $width > $height )? $width : $height;
				                if ( $edge <= $lboxMaxEdge ){
				                    if ( !isset($resizedEdge) ){
				                        $resizedId = $resize->getId();
				                        $resizedEdge = $edge;
				                    } else if ( $edge > $resizedEdge ){ 
				                        $resizedId = $resize->getId();
				                        $resizedEdge = $edge;
				                    } 
				                }
				            }
				            $theme['children'][$key]['resizedId'] = $resizedId;
				        }
				    }
				}
/* end add resizedId to child values, required for Lightbox JS */

Open your theme.tpl file in your text editor, and add the following stylesheet and javascript links, directly above the line that says </head>:

	{* stylesheet and javascript for Lightbox JS *}
	<link rel="stylesheet" type="text/css" href="{g->theme url="lightbox/css/lightbox.css"}" />
	<script type="text/javascript" src="{g->theme url="lightbox/js/prototype.js"}"></script>
	<script type="text/javascript" src="{g->theme url="lightbox/js/lightbox.js"}"></script>
	<script type="text/javascript" src="{g->theme url="lightbox/js/scriptaculous.js?load=effects,builder"}"></script>
	{* end stylesheet and javascript for Lightbox JS *}

Close your theme.tpl file, you're done with it.

Open your album.tpl file. On or about line 98, you'll see the following code:

		<div>
		  {if isset($theme.params.$frameType) && isset($child.thumbnail)}
		    {g->container type="imageframe.ImageFrame" frame=$theme.params.$frameType
				  width=$child.thumbnail.width height=$child.thumbnail.height}
		      <a href="{$linkUrl}">
			{g->image id="%ID%" item=$child image=$child.thumbnail
			 class="%CLASS% giThumbnail"}
		      </a>
		    {/g->container}
		  {elseif isset($child.thumbnail)}
		    <a href="{$linkUrl}">
		      {g->image item=$child image=$child.thumbnail class="giThumbnail"}
		    </a>
		  {else}
		    <a href="{$linkUrl}" class="giMissingThumbnail">
		      {g->text text="no thumbnail"}
		    </a>
		  {/if}
		</div>

Replace all of the above code with the following code:

<div>
  {if isset($theme.params.$frameType) && isset($child.thumbnail)}
    {g->container type="imageframe.ImageFrame" frame=$theme.params.$frameType width=$child.thumbnail.width height=$child.thumbnail.height}
{* alternate link code for Lightbox JS *}
		{if ($child.canContainChildren || $child.entityType == 'GalleryLinkItem' || $child.entityType == 'GalleryMovieItem')}
  			<a href="{g->url arg1="view=core.ShowItem" arg2="itemId=`$child.id`"}" >
  			{else}
<a href="{g->url arg1="view=core.DownloadItem" arg2="itemId=`$child.resizedId`"}"
    title="{$child.title|markup}"
    pageLink="{g->url arg1="view=core.ShowItem" arg2="itemId=`$child.id`"}"
    rel="lightbox[photos]" >
    {/if}
{*end alternate link code for Lightbox JS *}
   {g->image id="%ID%" item=$child image=$child.thumbnail class="%CLASS% giThumbnail"}
    </a>
    {/g->container}
  {elseif isset($child.thumbnail)}
		{if ($child.canContainChildren || $child.entityType == 'GalleryLinkItem' || $child.entityType == 'GalleryMovieItem')}
  			<a href="{g->url arg1="view=core.ShowItem" arg2="itemId=`$child.id`"}" >
  			{else}
 <a href="{g->url arg1="view=core.DownloadItem" arg2="itemId=`$child.resizedId`"}"
    title="{$child.title|markup}"
    pageLink="{g->url arg1="view=core.ShowItem" arg2="itemId=`$child.id`"}"
    rel="lightbox[photos]" >
    {/if}
   {g->image item=$child image=$child.thumbnail class="giThumbnail"}
    </a>
  {else}
    <a href="{g->url arg1="view=core.ShowItem" arg2="itemId=`$child.id`"}"
    class="giMissingThumbnail">
    {g->text text="no thumbnail"}
    </a>
  {/if}
</div>

Okay, now you're done editing album.tpl. You should not need to edit photo.tpl; the installation as described here essentially replaces photo.tpl with the Lightbox JS function.

Upload your theme folder to the server (or, if you just edited the three files, upload your edits to theme.inc, theme.tpl and album.tpl ).

There! That should be it, and Lightbox JS should now work well for you.

Without whom, or the Oscars speech

Thanks to scormeny (Sara Cormeny, http://www.paperlantern.com ) in the forums who wrote most of this tutorial.

Many thanks to Mike Miller at mikeage.net, who has a similar tutorial where he has also included a neat ZOOM modification that I did not use. http://mikeage.net/2006/09/03/gallery-2-lightbox/ .

The instructions and notes in the PGLightbox theme were also helpful in putting this together: http://codex.galleryproject.org/index.php/PGlightbox .

Lightbox JS 2.0.2 is cool, really cool! Hooray for Lokesh Dahar. http://www.huddletogether.com/projects/lightbox2/

And of course thanks to the whole team at Gallery, I am loving using this software for my web-design clients.

Additional Features

Making lightbox span multiple pages

Making lightbox span the pages of an album requires two things. The first thing is the lightbox module that is included with the Greypop theme. Then add the following code after the header of album.tpl

{assign var="total" value=0}
{assign var="first" value=0}
{assign var="last" value=0}
{math equation="x * y" x=$theme.params.columns y=$theme.params.rows assign=total}
{if ($theme.currentPage > 1)}
{math equation="(x - 1) * y + 1" x=$theme.currentPage y=$total assign=first}
{g->block type="lightbox.Before" class="Peers" windowSize=$theme.childCount first=$first}
{/if}

and this to the end of the file.

{if ($theme.currentPage < $theme.totalPages)}
{math equation="x * y" x=$theme.currentPage y=$total assign=last}
{g->block type="lightbox.After" class="Peers" windowSize=$theme.childCount last=$last}
{/if}

You must also do the next section for this mod to work properly. Credit goes to lvthunder in the forums for this modification.

Creating a fallback for browsers with Javascript disabled

Getting lightbox to fallback to the normal G2 photo layout requires editing lightbox.js and all the links to the images.

Edit the lightbox.js file with the following changes

line 62:
/* Hard coded the image paths */

line 181:
if(anchor.getAttribute('rev') && (relAttribute.toLowerCase().match('lightbox'))){

line 320:
new Effect.Appear('overlay', { duration: 0.2, from: 0.0, to: 0.6 });

line 331:
imageArray.push(new Array(imageLink.getAttribute('rev'), imageLink.getAttribute('title')));			

line 338:
if (anchor.getAttribute('rev') && (anchor.getAttribute('rel') == imageLink.getAttribute('rel'))){
imageArray.push(new Array(anchor.getAttribute('rev'), anchor.getAttribute('title')));

line 343:
while(imageArray[imageNum][0] != imageLink.getAttribute('rev')) { imageNum++;}

You also need to edit the links in album.tpl from

<a href="{g->url arg1="view=core.DownloadItem" arg2="itemId=`$child.resizedId`"}"
    title="{$child.title|markup}"
    pageLink="{g->url arg1="view=core.ShowItem" arg2="itemId=`$child.id`"}"
    rel="lightbox[photos]" >

to

<a href="{g->url arg1="view=core.ShowItem" arg2="itemId=`$child.id`"}" rev="{g->url arg1="view=core.DownloadItem" arg2="itemId=`$child.resizedId`"}" title="{$child.title|markup}" rel="lightbox[photos]">

Credit goes to sewpafly in the forums for this modification.


Adding a link to the existing photo details page

(I had nothing to do with creating any of the above, all credit goes to everyone else) This modification to the above adds a link to the normal photo display page under the thumbnail and also within the caption area of the Lightbox pop-up. I use this on http://gallery.jentulman.co.uk so that quite small resizes can be used for the Lightbox to act as a fast preview yet still allow easy access to higher res images.

Instead of the code suggested in the main example insert this at approx line 80 instead.

<div>
  {if isset($theme.params.$frameType) && isset($child.thumbnail)}
	{g->container type="imageframe.ImageFrame" frame=$theme.params.$frameType width=$child.thumbnail.width height=$child.thumbnail.height}
	{* alternate link code for Lightbox JS *}
	{if ($child.canContainChildren || $child.entityType == 'GalleryLinkItem' || $child.entityType == 'GalleryMovieItem')}
		<a href="{g->url arg1="view=core.ShowItem" arg2="itemId=`$child.id`"}" >{g->image id="%ID%" item=$child image=$child.thumbnail class="%CLASS% giThumbnail"}
		{else}
		<a href="{g->url arg1="view=core.DownloadItem" arg2="itemId=`$child.resizedId`"}"
			title="{$child.title|markup}"&lt;br /&gt;&lt;a href=&quot;{g->url arg1="view=core.ShowItem" arg2="itemId=`$child.id`"}&quot;&gt;Click for details.&lt;/a&gt;"
			pageLink="{g->url arg1="view=core.ShowItem" arg2="itemId=`$child.id`"}"
			rel="lightbox[photos]" >{g->image id="%ID%" item=$child image=$child.thumbnail class="%CLASS% giThumbnail"}</a><br />
		<a href="{g->url arg1="view=core.ShowItem" arg2="itemId=`$child.id`"}">View Other Sizes
	{/if}
	</a>
	{/g->container}
  {elseif isset($child.thumbnail)}
	{if ($child.canContainChildren || $child.entityType == 'GalleryLinkItem' || $child.entityType == 'GalleryMovieItem')}
		<a href="{g->url arg1="view=core.ShowItem" arg2="itemId=`$child.id`"}" >{g->image item=$child image=$child.thumbnail class="giThumbnail"}
		{else}
		 <a href="{g->url arg1="view=core.DownloadItem" arg2="itemId=`$child.resizedId`"}"
			title="{$child.title|markup}&lt;br /&gt;&lt;a href=&quot;{g->url arg1="view=core.ShowItem" arg2="itemId=`$child.id`"}&quot;&gt;Click for details.&lt;/a&gt;"
			pageLink="{g->url arg1="view=core.ShowItem" arg2="itemId=`$child.id`"}"
			rel="lightbox[photos]" >{g->image item=$child image=$child.thumbnail class="giThumbnail"}<br /></a>
		<a href="{g->url arg1="view=core.ShowItem" arg2="itemId=`$child.id`"}">View Other Sizes
	{/if}
	</a>
  {else}
	<a href="{g->url arg1="view=core.ShowItem" arg2="itemId=`$child.id`"}"
	class="giMissingThumbnail">
	{g->text text="no thumbnail"}
	</a>
  {/if}
</div>

It is this line

(line 9)      title="{$child.title|markup}&lt;br /&gt;&lt;a href=&quot;{g->url arg1="view=core.ShowItem" arg2="itemId=`$child.id`"}&quot;&gt;Click for details.&lt;/a&gt;"

In the above code that creates the link in the caption area. Note that the html to be used within the caption has had characters such as '<' written as their html entities to prevent breaking the javascript.

Mini Watermark Tutorial

WARNING: You can use watermarks ONLY IF the following applies to your Gallery:

  • You don't want to use any of the resize versions in the lightbox and only want to display the main picture. Tip: You can still get resizing by setting a "maximum image dimention" limit in album properties if this makes sense for your Gallery.

If above applies to you then follow below 2 points to get watermarks with lightbox:

  1. First of all complete the tutorial above as it is. Follow all points EXCEPT the changes to theme.inc - Ignore that part because we don't need the resized images information since we are not using the resized version. Now, since you skipped changes to theme.inc your lightbox will not work till you do the next part below. Don't panic if Gallery is not working till you finish point 2 below.
  1. Now edit album.tpl; In the last part of the tutorial above where you are doing changes in album.tpl - Look at those lines and replace $child.resizedId with $child.thumbnail.derivativeSourceId - Thats it! You will need to replace it 2 times as this is present in two different lines.

Now your lightbox should show the image with watermark.

Known limitations

  • With older versions of G2 watermarks will not be applied when using the lightbox hack. The current version (2.2.3) of G2 works fine. For older Versions, see above.
  • With Apple Safari: When an album contains pictures that have different "resizes" available (i.e. some pictures have bigger resizes available than others), the hack might show errorneous behaviour: Either lower resizes are scaled by the browser (and overflow lightbox' picture frame in the process) or higher resizes are disregarded - the picture frame is resized to the size of the higher resize though.
  • crosslinked album items will also open through lightbox as they cannot contain children (has been fixed in the above alternate album.tpl code by replacing {if $child.canContainChildren} with {if $child.canContainChildren || $child.entityType == 'GalleryLinkItem'} -- please review and delete this limitation note if everything is ok now and the hack does not create any problems--)
  • it seems lightbox cannot play movies in the created overlay. so in the current hack movie files have been excluded and open like always without lightbox...or is there a different solution to display streaming media in lightbox? discuss or post solution here please: http://galleryproject.org/node/59196#comment-218187
    • Important Note: Lightbox is intended only for photos by design. If you want to use other media, try to integrate Thickbox.
  • the image view count does not work anymore as the photopage is not requested. maybe some advanced programmer could implement a further hack to solve that issue when viewing images with lightbox hack. maybe the photopage could be requested somehow in the background without actually displaying it? discuss or post possible solutions here please: http://galleryproject.org/node/58419
  • lightbox hack will not work until the whole album page is loaded: a solution or enhancement would be to integrate a "Please wait" or "loading..." progress bar for loading pages so users do not get confused when clicking thumbnails before the page is loaded. ANy other suggestions?