Documentation

Here it is, all the Supersized documentation you're so eagerly waiting to read. Enjoy.


Glossary


Getting Started

First, you'll want to download the latest version of Supersized. Why? I have included all sorts of examples to serve as foundations for your projects - I've found this to be the easiest way. You're welcome.


Options

autoplay

Determines whether slideshow begins playing when page is loaded.

type : boolean
default : 1

fit_always

Prevents the image from ever being cropped. Ignores minimum width and height.

type : boolean
default : 0

fit_landscape

Prevents the image from being cropped by locking it at 100% width.

type : boolean
default : 0

fit_portrait

Prevents the image from being cropped by locking it at 100% height.

type : boolean
default : 1

horizontal_center

Centers image horizontally. When turned off, the images resize/display from the left of the page.

type : boolean
default : 0

image_protect

Disables right clicking and image dragging using Javascript.

type : boolean
default : 1

keyboard_nav

Allows control via keyboard.

type : boolean
default : 1

min_height

Minimum height the image is allowed to be. If it is met, the image won't size down any further.

type : number
default : 0

min_width

Minimum width the image is allowed to be. If it is met, the image won't size down any further.

type : number
default : 0

new_window

Slide links open in a new window.

type : boolean
default : 1

pause_hover

Pauses slideshow while current image hovered over.

type : boolean
default : 0

performance

Uses image rendering options in Firefox and Internet Explorer to adjust image quality. This can speed up/slow down transitions. Webkit does not yet support these options.

type : number
default : 1

random

Slides are shown in a random order. start_slide is disregarded.

type : boolean
default : 0

slides

The array containing all your images with image, title, url, and any custom fields. You can delete any fields you are leaving empty.

type : array
default : null

slideshow

Turns the slideshow on/off. Disables navigation and transitions.

type : boolean
default : 1

slide_interval

Time between slide changes in milliseconds.

type : number
default : 5000

Generates a list of links that jump to the corresponding slide.

type : string
default : 0

start_slide

The slide the slideshow starts on. *In the Core version, it controls which image is loaded, 0 causes a random image to be loaded each time.

type : number
default : 1

stop_loop

Pauses slideshow upon reaching the last slide.

type : boolean
default : 0

Generates a list of thumb links that jump to the corresponding slide. If the 'thumb' field for the slide is empty, it will simply scale down the full size image, which can slow performance.

type : boolean
default : 0

thumbnail_navigation

Toggles forward/backward thumbnail navigation. When on, thumbnails from the next/previous posts are generated and can be clicked to navigate. If the 'thumb' field for the slide is empty, it will simply scale down the full size image.

type : boolean
default : 0

transition

Controls which effect is used to transition between slides.

type : number or string
default : 1

transition_speed

Speed of transitions in milliseconds.

type : number
default : 750

vertical_center

Centers image vertically. When turned off, the images resize/display from the top of the page.

type : boolean
default : 1

API

There are a number of core functions which are accessible via API calls. For theme specific calls, check the Themes API section.

api.nextSlide( )

Triggers transition to the next slide.

$(element).click(function(){
	api.nextSlide();
});

api.prevSlide( )

Triggers transition to the previous slide.

$(element).click(function(){
	api.prevSlide();
});

api.goTo( targetSlide )

Triggers transition to target slide number.

// Goes to slide #5
$(element).click(function(){
	api.goTo(5);
});

api.playToggle( )

Toggles between pause/play states. Changes the vars.is_paused variable to true/false accordingly.

$(element).click(function(){
	api.playToggle();
});

api.getField( field )

Returns the value of the specified field for the slide (from the slide array)

$(document).ready(function(){
	var slideTitle = api.getField('title');
	alert(slideTitle);
});

api.options.some_option

Allows access to all options (theme and base combined).

$(document).ready(function(){
	if (api.options.auto_play){
		alert('Autoplay is enabled!');
	}
});

Variables

In addition to API functions, you can also access a number of variables, the key ones are listed below.

vars.current_slide

Stores the current slide number.

type : number

vars.is_paused

If the slideshow is paused, this value will be true.

type : boolean

vars.in_animation

This variable is true whenever slides are transitioning. Prevents buildup.

type : boolean

Theme API

Since the release of version 3.2.0, the core functionality of Supersized has been separated from the styles, which is where themes come in. The Shutter Theme is included as the default theme, but as you develop it out for your own purposes, you'll likely want to make a theme file all your own.

Aside from the above API calls, there are select theme.someFunction() functions to help you with your theming (highlighted below). You define these from within your theme.

theme._init( )

Houses the majority of your theme functionality, as it is the first theme function called once the initial slide loads.

trigger : first image loaded

theme.beforeAnimation( direction )

Runs prior to each slide transition and when the slideshow first loads. Passed either 'next' or 'prev'. This is a good place to update fields such as caption and slide number using the api.getField() function.

trigger : slideshow start / before each slide transition

theme.afterAnimation( )

Runs each time a slide transition is completed.

trigger : after each slide transition

theme.playToggle( state )

Called each time the slideshow swaps between pause/play. The current state, 'pause' or 'play' is passed in accordingly.

trigger : api.playToggle()

theme.goTo( )

Runs when api.goTo() is used.

trigger : api.goTo()

Theme Variables

From within your theme file, you are able to include additional parameters such as variables or options. It is important to note that the hierarchy goes user > theme > default, where user represents the options passed in when Supersized is first called. Since these vary theme to theme, checking the documentation for your particular theme is the best bet.