TN3 API

To understand how the TN3 API functions you first need to have basic understanding of jQuery. If you don’t have prior knowledge of jQuery please take a few minutes to familiarise yourself with the contents of this tutorial before using the TN3 API.

Static Methods

jQuery.fn.tn3.translate(string, translation)
Changes the string used by the TN3 Gallery.

The following strings can be translated: “Album List”, “Close”, “Maximize”, “Minimize”, “Next Album Page”, “Next Image”, “Next Page”, “Pause Video”, “Play Video”, “Previous Album Page”, “Previous Image”, “Previous Page”, “Start Slideshow” and “Stop Slideshow”.

Example:

    $(document).ready(function() {
      $.fn.tn3.translate("Maximize", "FullScreen");
    });
   

 

Static Properties

jQuery.fn.tn3.config
.data
.skin
.skinDir
.skinDefault
.cssID
jQuery.fn.tn3.Gallery.config
.active
.autoplay
.delay
.fullOnly
.width
.height
.iniAlbum
.iniImage
.imageClick
.startWithAlbums
.timerMode
.timerSteps
.timerStepChar
jQuery.fn.tn3.Imager.config
.defaultTransition
.clickEvent
.crop
.idleDelay
.maxZoom
.random
jQuery.fn.tn3.Thumbnailer.config
.align
.buffer
.overMove
.shaderColor
.shaderDuration
.shaderOpacity
.shaderOut
.slowdown
.seqLoad
.useTitle
.speed

These config objects store default values for TN3 parameters. Refer to the TN3 Parameters for a detailed description of each property.

The following example will set the slideshow to always start automatically, even if the autoplay property is not set in the plug-in initialization object:

$(document).ready(function() {
  $.fn.tn3.Gallery.config.autoplay = true;
 });

 

API Scope

All methods and properties (except static ones) in this reference refer to the instance of the TN3 gallery which is returned as the ‘tn3′ property of the jQuery ‘data’ object which itself is returned at tn3 plug-in initialization. In the following example, the JavaScript variable ‘$mytn3′ refers to an instance of the TN3 gallery:

$(document).ready(function() {
    var $mytn3 = $('.gallery').tn3({
      autoplay: true
    }).data('tn3');
    // call fullscreen method on instance of tn3 gallery
    $mytn3.fullscreen();
});

Note: If the TN3 is set to load an external skin, you should only use the API after the ‘init’ event has been triggered.

 

Methods

.fullscreen()
Toggles between ‘normal’ and fullscreen mode.

Example:

$mytn3.fullscreen();

.resize(width, height)
Changes the width and height of the gallery.

Example:

$mytn3.resize(400, 300);

.show(n)
Shows the ‘n’ image in the gallery. The value of the parameter ‘n’ can be any integer (JavaScript indexes begin at 0 so use 0 for the first image, 1 for the second image and so forth). Alternately you can use the strings “next” or “prev” to move to the adjacent images in the slideshow.

The following example will display next image in the gallery:

$mytn3.show("next");

.showAlbum(albumID, imageID)
Displays and makes the album in a multi-album gallery active. The value of the parameters ‘albumID’ and ‘imageID’ can be any integer (0 for the first, 1 for second etc).

The following example will display the second image of the third album in the gallery:

$mytn3.showAlbum(2, 1);

.setAlbumData(data)
Sets data for the gallery albums. See TN3 Data for more information on data structure.

Example:

$mytn3.setAlbumData(dataArray);

.setImageData(data, albumID)
Sets data for images in the album. See TN3 Data for more information on data structure.

Example:

$mytn3.setImageData(dataArray, albumID);

.rebuild(data, imageID)
Sets the main data object and reinitializes the gallery. See TN3 Data for more information on the TN3 Gallery’s data structure.

Example:

$mytn3.rebuild(dataArray, imageID);

 

Properties

.data – gallery data array (see ‘Data array’ below)
.cAlbum – index of the currently active album
.n – index of the currently active image
.thumbnailer – instance of the thumbnailer
.imager – instance of the imager

The following example will display and alert containing the index of the currently active album:

alert($mytn3.cAlbum);

 

TN3 Data array

The TN3 Gallery data is an array of album objects. Each album object contains properties:

imgs – an array of the image objects, required
thumb – the URL of the album thumbnail
title – the title of the album
description – the description of the album

Each image object, from the ‘imgs’ array, should contain:

thumb – the URL of the image thumbnail, required
img – the URL of the main image, required
title – the title of the image
description – a description for the image

You can add other properties to both album and image objects if you need to. The image object has a special property named ‘content’ (added from v1.2) that will, if defined, display HTML content instead of an image. This property is also used when displaying videos.

The TN3 Gallery will only initialize when the data objects exists. The ‘init_start’ event is triggered before initialization provided there is a valid data object. So you can use this event to modify or set your own data.

$(document).ready(function() {
    var $mytn3 = $('.gallery').tn3({
		init_start:function(e) {
			e.source.data = [{
			    title: "My Album",
			    thumb: "/images/114x72/1.jpg",
			    imgs: [{
			        title: "Image One",
			        thumb: "/images/114x72/9.jpg",
			        img: "/images/920x360/9.jpg"
			    }, {
			        title: "Image Two",
			        thumb: "/images/114x72/9.jpg",
			        img: "/images/920x360/9.jpg"
			    }, {
			        title: "Image Three",
			        thumb: "/images/114x72/9.jpg",
			        img: "/images/920x360/9.jpg"
			    }]
			}];
		}
    }).data('tn3');
});