Default Settings

The image cube functionality can easily be added to a division with appropriate default settings. It then displays the images contained within the targetted division in a cycle every two seconds. A random rotation is chosen each time to move to the next image. Highlights and shadows are used to enhance the 3D effect.

Stop and restart the automatic rotation with the appropriate commands.

You can also remove the image cube functionality with the 'destroy' command if it is no longer required.

Basic cube:

Uluru Islands Gorge
<div id="defaultCube" style="width: 200px; height: 150px;">
	<img src="uluru.jpg" alt="Uluru" title="Uluru"/>
	<img src="islands.jpg" alt="Islands"title="Islands"/>
	<img src="gorge.jpg" alt="Gorge" title="Gorge"/>
</div>
$('#defaultCube').imagecube();

$('#stopCube').click(function() {
	var start = $(this).text() === 'Start';
	$(this).text(start ? 'Stop' : 'Start');
	$('#defaultCube').imagecube(start ? 'start' : 'stop');
});

$('#removeCube').click(function() {
	var destroy = $(this).text() === 'Remove';
	$(this).text(destroy ? 'Re-attach' : 'Remove');
	$('#defaultCube').imagecube(destroy ? 'destroy' : {});
});

You can override the defaults globally as shown below:

$.imagecube.setDefaults({speed: 1000, pause: 5000});

Processed fields are marked with a class of is-imagecube and are not re-processed if targetted a second time.

Rotation Controls

Control how the image cube works by supplying various options when attaching it. You can change the options on the fly with $(selector).imagecube('option', {...}). You can trigger a new rotation with $(selector).imagecube('rotate'). This command can also take a selector for the next face to show, and/or a callback function to notify you of the completion of the rotation.

Change rotation direction and target: to

Uluru Islands Gorge

  Now showing: Uluru

$('#directionCube').imagecube({direction: 'up', repeat: false});

$('#directionButton').click(function() {
	var cube = $('#directionCube');
	var next = parseInt($('#next').val(), 10);
	cube.imagecube('option', {direction: $('#direction').val()}).
		imagecube('rotate', next, function() {
			$('#current').text($(cube.imagecube('current')).attr('title'));
		});
});

Control how the next image to be shown is selected. The normal order here is Uluru, islands, gorge.

Next image:

Uluru Islands Gorge

  Next rotation: Uluru » Islands

$('#selectionCube').imagecube({direction: 'left', afterRotate: showNext});
	
function showNext() {
	$('#currentNext').text($('#selectionCube').imagecube('current').title +
		' » ' + $('#selectionCube').imagecube('next').title);
}

$('#selection').change(function() {
	$('#selectionCube').imagecube('option',
		{selection: $('#selection').val()});
});
Effect Controls

Change rotation speed: ms for rotation with ms pause

 and easing

Uluru Islands Gorge
$('#speedCube').imagecube({speed: 5000, easing: 'easeOutBounce'});

$('#effects select').change(function() {
	$('#speedCube').imagecube('stop').
		imagecube('option', {speed: parseInt($('#speed').val()),
			pause: parseInt($('#pause').val()), easing: $('#easing').val()}).
		imagecube('start');
});

No shading effects:

Uluru Islands Gorge
$('#plainCube').imagecube({shading: false});
Random Rotations

You can control from which directions a random selection is made.

Random up/down:

Uluru Islands Gorge
$('#upDownCube').imagecube({randomSelection: ['up', 'down']});

Random left/right:

Uluru Islands Gorge
$('#leftRightCube').imagecube({randomSelection: ['left', 'right']});
Rotation Callbacks

There are two callbacks available: one just as the rotation is starting and another as the rotation ends.

Before/after rotation:

Uluru Islands Gorge

  Status:

$('#callbackCube').imagecube(
	{beforeRotate: startingRotate, afterRotate: endedRotate});

function startingRotate(current, next) {
	$('#rotateStatus').text('starting ' + $(current).attr('title') +
		' » ' + $(next).attr('title'));
}

function endedRotate(current, next) {
	$('#rotateStatus').text('ended ' + $(current).attr('title') +
		' » ' + $(next).attr('title'));
}
Text Cube

You can also rotate text, but the effect is not quite as good. Note that each child may have its own colours, borders, and padding.

Text cube:

Once a jolly swagman camped by a billabong under the shade of a coolabah tree. And he sang as he watched and waited till his billy boiled. "Who'll come a-waltzing Matilda...
Out on the board the old shearer stands, grasping his shears in his thin bony hands. Fixed is his gaze on a bare-bellied yoe, glory if he gets her, won't he make the ringer go...
Australians all let us rejoice for we are young and free. We've golden soil and wealth for toil, our home is girt by sea. Our land abounds in nature's gifts of beauty...
<div id="textCube" style="width: 200px; height: 150px;">
	<div style="background-color: #FAA;">Once a jolly swagman...</div>
	<div style="background-color: #AFA; padding: 5px 5px;
			border: 2px solid lime;">
		Out on the board the old shearer stands,...</div>
	<div style="background-color: #AAF; padding: 3px 3px;
			border: 5px double rgb(0, 0, 255);">
		Australians all let us rejoice...</div>
</div>
$('#textCube').imagecube();

Text cube without shading:

Once a jolly swagman camped by a billabong under the shade of a coolabah tree. And he sang as he watched and waited till his billy boiled. "Who'll come a-waltzing Matilda...
Out on the board the old shearer stands, grasping his shears in his thin bony hands. Fixed is his gaze on a bare-bellied yoe, glory if he gets her, won't he make the ringer go...
Australians all let us rejoice for we are young and free. We've golden soil and wealth for toil, our home is girt by sea. Our land abounds in nature's gifts of beauty...
$('#textPlain').imagecube({shading: false});

Link banner:

$('#textBanner').imagecube({
	direction: 'up', speed: 500, full3D: false, shading: false});
3D Effect Controls

The 3D effect can be tuned with the following settings. The reduction and expansion settings give you control over the sizing of the cube by changing the amount that the far edges decreases in size and that the near edge increases in size. The segments setting controls how many pieces each image is divided into for the effect.

Full 3D cube: Reduction   Expansion   Segments

Uluru Islands Gorge
$('#full3DCube').imagecube({speed: 3000});

$('#reduction,#expansion,#segments').change(function() {
	$('#full3DCube').imagecube('option', {reduction: $('#reduction').val(),
		expansion: $('#expansion').val(), segments: $('#segments').val()});
});

The original pseudo-3D rotation (without perspective) is still available.

Pseudo 3D cube:

Uluru Islands Gorge
$('#flatCube').imagecube({full3D: false});

Text cube:

Once a jolly swagman camped by a billabong under the shade of a coolabah tree. And he sang as he watched and waited till his billy boiled. "Who'll come a-waltzing Matilda...
Out on the board the old shearer stands, grasping his shears in his thin bony hands. Fixed is his gaze on a bare-bellied yoe, glory if he gets her, won't he make the ringer go...
Australians all let us rejoice for we are young and free. We've golden soil and wealth for toil, our home is girt by sea. Our land abounds in nature's gifts of beauty...
$('#flatTextCube').imagecube({full3D: false});
In the Wild

This tab highlights examples of this plugin in use "in the wild".

To add another example, please contact me (wood.keith{at}optusnet.com.au) and provide the plugin name, the URL of your site, its title, and a short description of its purpose and where/how the plugin is used.

Quick Reference

A full list of all possible settings is shown below. Note that not all would apply in all cases. For more detail see the documentation reference page.

$(selector).imagecube({
	direction: 'random', // Direction of rotation: random|up|down|left|right
	randomSelection: ['up', 'down', 'left', 'right'],
		// If direction is random, select one of these
	speed: 2000, // Time taken (milliseconds) to transition
	easing: 'linear', // Name of the easing to use during transitions
	repeat: true, // True to automatically trigger a new transition after a pause
	pause: 2000, // Time (milliseconds) between transitions
	selection: 'forward', // How to choose the next item to show:
		// 'forward', 'backward', 'random'
	shading: true, // True to add shading effects, false for no effects
	opacity: 0.8, // Maximum opacity (0.0 - 1.0) for highlights and shadows
	imagePath: '', // Any extra path to locate the highlight/shadow images
	full3D: true, // True to add cubic perspective, false for 2D rotation
	segments: 20, // The number of segments that make up each 3D face
	reduction: 30, // The amount (pixels) of reduction for far edges of the cube
	expansion: 10, // The amount (pixels) of expansion for the near edge of the cube
	lineHeight: [0.0, 1.25], // Hidden and normal line height (em) for text
	letterSpacing: [-0.4, 0.0], // Hidden and normal letter spacing (em) for text
	beforeRotate: null, // Callback before rotating
	afterRotate: null // Callback after rotating
});

$.imagecube.setDefaults(options) // Set global defaults

$(selector).imagecube('option', options) // Change multiple settings
$(selector).imagecube('option', name, value) // Change a single setting
$(selector).imagecube('option', name) // Retrieve a setting

$(selector).imagecube('destroy') // Remove image cube functionality

$(selector).imagecube('rotate', next, callback) // Rotate to next face
$(selector).imagecube('stop') // Stop automatic rotation
$(selector).imagecube('start') // Restart automatic rotation

$(selector).imagecube('current') // Retrieve the current face
$(selector).imagecube('next') // Retrieve the next face