Documentation

Elixon Theatre

Elixon Theatre is an extensible carousel/slideshow-like JQuery plugin supporting multiple animation effects. Works with images or any other type of rich formatted HTML contents. A best choice for portfolios, news tickers, image showcases and more. It provides you the freedom of custom controls. You can design your own controls as you like. Or you can use inbuilt support for button templates. Just create a button template and point Elixon Theatre to your button template using the paging property.

Motivation

Yet another jQuery carousel? Why?

My main goal is to lead a development of CMS systems so CMS become a maintainable professional tool that enables designers and editors to create a great sites without limiting their fantasy. During a decade in the CMS business I've learned that

no matter how good the tool is the fantasy of designers always exceeds it

They don't want to have one gallery. They want to have many types of galleries. They don't want to have vertical slideshow, they want to have also horizontal and fade in/out slideshows. And it makes sense. We can be very conservative regarding content editing features but we must not be conservative about design of the websites. The website is a front end of the company and every company must distinguish itself from others. Thus allowing every site to be as different as possible is essential to our business.

Sure, there is always some great jQuery plugin that does the job. But sooner then later you will end up supporting five slightly different jQuery plugins that do almost the same thing. And once you include the support of particular plugin into CMS release then you become responsible for maintenance of the plugin for a whole life cycle of a website. It results in waste of time and money. You will need other solution soon.

And this is why I started Elixon Theatre. I didn't want any software maintainer to be responsible for many different plugins doing the same job. Soon enough I realized that all these carousel effects can be just one jQuery plugin that meets following goals:

Maintainability
CMS release maintainers need to worry about compatibility and updates for just one jQuery plugin.
Learn Once & Use Often
Designers don't need to learn many different APIs - just one simple API for all carousel effects they need.
Safe Extensibility
Anybody can add new effects in a safe way as independent add-ons without altering/breaking the core code.
Per-site Customizations
Elixon Theatre is as much CSS friendly as possible and allows per-site custom-designs including fully customizable control buttons.

Definitions

Theatre: This plugin.
Stage: JQuery object representing the container with items to animate.
Actor: HTML element representing the item to be animated inside the Stage.
Settings: Javascript array with settings passed to the Theatre's constructor.
Effect: Javascript object providing the effect animation.

Requirements

In addition to JQuery 1.4 you need to link the Theatre Javascript and CSS file from within your page.

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js" 
        type="text/javascript"></script>

<link type="text/css" rel="stylesheet" href="…/theatre/theatre.css" />
<script type="text/javascript" src="…/theatre/jquery.theatre.min.js"></script>

Syntax

$(Stage).theatre(Settings); Initialize the Theatre
$(Stage).theatre('next'); Jump to next Actor
$(Stage).theatre('prev'); Jump to previous Actor
$(Stage).theatre('play'); Start cycling through the list of Actors
$(Stage).theatre('stop'); Stop the automatic cycling
$(Stage).theatre('jump', index [, speed^1.0.10]); Jump to the given Actor where index is 'first' (same as 1), 'last'^1.0.2 or number. Optional speed^1.0.10 parameter specifies the transition speed.
$(Stage).theatre('effect', name, effect); Register a custom animation object. See more bellow.

Settings

You can pass the array of settings to the theatre method: $(Stage).theatre(Settings); where Settings properties are:

effect

String containing the white-space separated effect names or object providing the effect.

You can specify multiple white-space separated effect names - main effect and fall over effect(s) for the case that the browser is not capable of displaying selected effect.

Possible values: horizontal, vertical, fade, show, slide, 3d, css3:circle, css3:slide, css3:stack or custom effect name or Effect.

Default: horizontal

Example: $('#my').theatre({effect: 'css3:stack horizontal'}); /* if the browser does not support CSS3 transformations fall back to 'horizontal' effect */

speed

Animation speed in milliseconds. Default: 500

still

Time between two animations. Default: 3000

autoplay

Start animations automatically. Default: true

controls

Display default next/previous/play/stop controls. Values: horizontal or vertical or none. Default: horizontal

width

Set the width of the Stage or false to leave the original size. Default: false

height

Set the height of the Stage or false to leave the original size. Default: false

itemWidth^1.0.2

false - don't resize; 'max' - maximum size; arbitrary size ('100px', '50%', ...). Default: false

itemHeight^1.0.2

false - don't resize; 'max' - maximum size; arbitrary size ('100px', '50%', ...). Default: false

selector

CSS selector to identify the Actors inside the Stage. Default: > *:not(".theatre-control")

onMove

Optional callback method to be called before each animation. The target index and target displayed Actor^1.0.5 is passed to the method. Callback context (this) is the Stage HTML element.

Stage.theatre({onMove: function(idx, actor, theatre^1.0.8) { doSomething(idx, actor);} }); If you return false from this method then movement will be cancelled. If you return number then Theatre will jump to returned position instead.

^1.0.8In addition to this an event theatreMove is fired on Stage element. So instad of onMove property you may use

Stage.bind('theatreMove', function(idx, actor, theatre) {});

onAfterMove^1.18

Same as onMove callback but is called after the transition animation finishes. idx and actor parameters to this callback represent the currently active Actor. Unlike onMove the return value is ignored.

playDir^1.17

Default: next . You can reverse the direction of rotation by supplying prev keyword.

random^1.17

Default: false. If set to true then Actors will be reshuffled before Theatre initialization.

paging^1.0.6

Optional jQuery selector pointing to an element containing the button template. Children template element will be duplicated to match the number of actors and will gain the onClick functionality to jump to specified actor. If the template contains the string {#} then it will be replaced by ordinal actor number. Active button has always the active class name.

<div id="myPaging"><button class="jump">{#}</button></div>

Stage.theatre({paging: '#myPaging'});

Paging

^1.0.6

You can create fully customized paging buttons.

		<div id="myPaging">
		<!-- template button -->
		<button class="myPaging">Jump to {#}</button>
		</div>

		<script type="text/javascript">
		$('#myTest').theatre({…, paging: "#myPaging"});
		</script>

Examples

Full Simplified Example


  <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js" 
          type="text/javascript" ></script>
  <link type="text/css" rel="stylesheet" href="…/theatre/theatre.css" />
  <script type="text/javascript" src="…/theatre/jquery.theatre.min.js"></script>

  <div id="demo">
	<div>My Item #1</div>
	<div>My Item #2</div>
	<div>My Item #3</div>	
  </div>

  <script type="text/javascript">
	$(function() {
	  $('#demo').theatre();
	});
  </script>

Full Advanced Example

This example shows how to deal with images surrounded by links.


  <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js" 
          type="text/javascript" ></script>
  <link type="text/css" rel="stylesheet" href="…/theatre/theatre.css" />
  <script type="text/javascript" src="…/theatre/jquery.theatre.min.js"></script>

  <div id="demo">
	<a href="/detail1.jpg"><img src="/preview1.jpg"/></a>
	<a href="/detail2.jpg"><img src="/preview2.jpg"/></a>
	<a href="/detail3.jpg"><img src="/preview3.jpg"/></a>	
  </div>

  <div id="myPaging"><span class="button">Image #{#}</span></div>

  <script type="text/javascript">
	$(window).load(function() {
	  $('#demo').theatre({
	    selector: 'img', // We want to resize/rotate images and not links
		effect: '3d',
		speed: 1000,
                paging: '#myPaging'
	  });

	  // $('#demo a').fancybox();
	});
  </script>

Custom Effects

Do you want to write your own JQuery carousel plugin or some other really fancy slideshow? Why to reinvent the wheel? Big deal of code that you are going to write is already in Elixon Theatre! Just use the Elixon Theatre as the base and fully focus on your core animation idea. We took a care of creating extremely easy and well thought out Effect API that you are going to love!

Start writing your own Effect plugin for Theatre right away!

Effect is a Javascript object implementing following methods:

init() - initialize the Stage
next() - jump to next Actor
prev() - jump to previous Actor
destroy() - remove all modifications made to the Stage
jump(idx) - optional. Optimized "jump to" routine. If not present then system automatically uses next()/prev() methods to reach a desired point.

The Effect object is initialized as follows

new Effect(Stage, Actors, Settings, Theatre)

Effect Registration

There are two ways how to register your effect. You can register it under new name or pass it as an object to a Settings

$.fn.theatre('effect', Name, Object);
$(Stage).theatre({effect: Object});

Example

Content of the effect.magnificent.js file (see Lazy Loaded Effects bellow for details):


(function($) {
  var myEffect=function(stage, actors, settings, theatre) {
    this.init=function() {
      actors.hide(0).first().show(0);
    }
    this.next=function() {
      actors.stop(true, true).css('z-index', 0).hide(settings.speed)
        .eq(theatre.index).css('z-index', 10).show(settings.speed);
    }
    this.prev=function() {
      actors.stop(true, true).css('z-index', 0).hide(settings.speed)
        .eq(theatre.index).css('z-index', 10).show(settings.speed);
    }
    this.destroy=function() {
      actors.stop(true, true).css({
  	  zIndex: '', top: '', left: '', position: '', margin: ''
  	  }).show(0);
    }
  }
  $.fn.theatre('effect', 'magnificent', myEffect);
})(jQuery)

Usage:


$(function() {
  $('#demo').theatre({effect: 'magnificent'});
});

^{Since 1.0.1}

Lazy Loaded Effects

There may be many effect ready to use. There is a lazy effect initialization supported to prevent loading all effects unnecessarily.

If you evoke unknown effect then Theatre tries to include a javascript file of the same name effect.Name.js from the same directory as the base Theatre files.

For example ('#demo').theatre({effect: 'moonlight'}); will load the script effect.moonlight.js and execute it. This script is supposed to register the Effect object by calling $.fn.theatre('effect', 'moonlight', Effect);

Multiple Effects In One File

One script may register multiple different effects. In that case the effects must be prefixed by file name.

For example have a file effect.extra.js that introduces two effects crazy and reflection. In that case you have to prefix both names by the script name extra so the effect names will be extra:crazy and extra:reflection.

When you call ('#demo').theatre({effect: 'extra:crazy'}); then Theatre will load the effect file with name extra (effect.extra.js) that is supposed to register the effect extra:crazy by calling $.fn.theatre('effect', 'extra:crazy', Effect); .