How-to add Lightbox v2 to a Subtext skin

Yesterday I added Lightbox v2 to my skin. So here is a step by step guide on how to do it.

Step 1: Download library

Download Lightbox 2.02 and extract it on a folder of your choice.

Step2: Skin Definition

Change the skin definition inside skin.config or skin.user.config adding the following lines inside the <Scripts> tag:

<Script Src="scripts/prototype.js" />
<Script Src="scripts/scriptaculous.js?load=effects" />
<Script Src="scripts/lightbox.js" />

And that inside the <Styles> tag:

<Style href="lightbox.css" />

If you are upgrading from the version of lightbox that is coming with Subtext you have to remove the following lines, too:

<Script Src="~/scripts/lightbox.js" />
<Style href="~/scripts/lightbox.css" />

In the case you don't have anything else, then your skin definition should be something link:

<SkinTemplate Name="lightbox2EnabledSkin"
        TemplateFolder="lightbox2EnabledSkin">
    <Scripts>
        <Script Src="scripts/prototype.js" />
        <Script Src="scripts/scriptaculous.js?load=effects" />
        <Script Src="scripts/lightbox.js" />
    </Scripts>
 
    <Styles>
        <Style href="lightbox.css" />
    </Styles>
</SkinTemplate>

Step 3: Modify images path

Since lightbox script and its CSS references images using their full path, next thing you need to change is the location of images: you need to change is inside 2 files.

js/lightbox.js (first 2 lines of JavaScript excluding the comments):

var fileLoadingImage = "/skins/<yourskinName>/images/loading.gif";
var fileBottomNavCloseImage = "/skins/<yourskinName>/images/closelabel.gif";

and css/lightbox.css: here you have to look for all the places that have a "../images/" and replace it with "/skins/<yourskinName>/images/"

Step 4: Copy files to production server

Now that all the changes are done, you have to copy all the files to the production server:

css/lightbox.css goes into the skin root folder (/skins/<yourskinName>/)
all js files (prototype.js, scriptaculous.js, lightbox.js and effects.js) go into the skin script folder (/skins/<yourskinName>/scripts)
all the gif files that are inside images folder must be copied to the skin images folder (/skins/<yourskinName>/images)
last update the skin.config (or skin.user.config) skin configuration file

(If you don't see the changes then you need to recycle your website, if you don't have access to an IIS admin tool, just rename web.config to web.config.1 and rename it back after a few seconds)

Step 5: How to include a lightbox enabled image

Nothing is changed from the previous version, so all your old images will go on working they way they did before.

Adding an image is easy: just do as if you want to open the full-size image in a new page, than add a rel attribute with a value of "lightbox" to the anchor tag.

<a href="fullimageUrl" rel="lightbox" title="caption"><img src="thumbUrl" /></a>

And if you want to use the new feature added with version 2, the gallery, you just need specify lightbox[galleryname] as rel attribute.

<a href="fullimageUrl1" rel="lightbox[galleryname]" title="caption 1"><img src="thumbUrl1" /></a>
<a href="fullimageUrl2" rel="lightbox[galleryname]" title="caption 2"><img src="thumbUrl2" /></a>
<a href="fullimageUrl3" rel="lightbox[galleryname]" title="caption 3"><img src="thumbUrl3" /></a>

I just added a feature request on sourceforge for next version of Subtext, and I'm going to add lightbox v2 inside the 1.9 branch, so hopefully adding a lightbox would be easier in a few months.