What is jVariations?

// checkbox // "What is jVariations?"
$('p:lt(3)').jVariation('Show "What is jVariations?"');

jVariations is a tool that generates a control panel to show and hide variations (aka corner cases) in a single HTML template.

Why? When providing HTML templates to server-side engineers or clients, I got tired of having separate files to show each variation... think error messages, varying number of tabs, etc. Now you can demonstrate all those variations in one HTML file without otherwise modifying the source HTML.

Download jVariations (fully-commented, uncompressed)
Documentation included in JavaScript file

Examples (use control panel to manipulate)

1. Toggle between elements (show one at a time)

// radio button // paragraph 3
$('p:eq(3)').jVariation({
     label: 'Show Paragraph 3, hide 4 & 5',
     group: 'toggleBetween'
});

// radio button // paragraph 4
$('p:eq(4)').jVariation({
     label: 'Show Paragraph 4, hide 3 & 5',
     autoHide: true,
     group: 'toggleBetween'
});

// radio button // paragraph 5
$('p:eq(5)').jVariation({
     label: 'Show Paragraph 5, hide 3 & 4',
     autoHide: true,
     group: 'toggleBetween'
});

This is the first paragraph of the group. The other two paragraphs are hidden by default, because jVariations tells them to .hide(). Click on "Show Paragraph 4" to see the next paragraph.

This is the second paragraph of the group. Notice that whatever item was previously visible is now hidden. In this case it's using the default .hide() ... but you could just as well write a custom onHide function.

This is the third paragraph of the group. It's much shorter than the other two paragraphs.

2. Toggle class name (there is only one element)

// checkbox and radio buttons chained together    
$('p:eq(6)').jVariation({ // checkbox    
	 id: 'showToggleClass',    
	 label: 'Show "toggle class name" example',    
	 onShow: function(){ this.slideDown(); },    
	 onHide: function(){ this.slideUp(); }    
}).jVariation({ // radio button 1    
	 require: 'showToggleClass',    
	 label: 'Default paragraph style (no class)',    
	 onShow: function(){ this.removeClass(); },    
	 onHide: false,    
	 group: 'toggleClass'    
}).jVariation({ // radio button 2    
	 require: 'showToggleClass',    
	 label: 'Add "error" class',    
	 onShow: function(){ this.addClass('error'); },    
	 onHide: false,    
	 autoHide: true,    
	 group: 'toggleClass'    
});

There are a couple of things going on in this example. 1) You'll note that the HTML is very simple: There's only one paragraph tag! 2) The paragraph's class name is modified by the radio buttons. 3) If the paragraph tag is hidden when a radio button is selected it will be shown automatically. To do this I assigned an id to the Show "toggle class name" example checkbox and then set the require property of the radio buttons to that id.

Simplified Usage (for reference)

jVariations works with (1) no parameters, (2) a string parameter, or (3) an object pararmeter. Note, all properties are optional. Also, they can be mixed and matched together to achieve desired results. Confused? See the code samples below or a description of configurable options further down.

// add a checkbox to the control panel with a label of "Show Variation #"
$('p').jVariation();

// add a checkbox to the control panel with a label of "Show all paragraphs"
$('p').jVariation("Show all paragraphs");

// add a checkbox to the control panel with a label of "Show all paragraphs"
$('p').jVariation({ label: "Show all paragraphs" });

// add an unchecked checkbox to the control panel
// the paragraphs will be hidden using the default .hide()
$('p').jVariation({ autoHide: true });

// creates three variations that are mutually exclusive
// adds three radio buttons to control panel and groups them together
// autoHide the last two variations (so the first radio button is selected)
$('#promoTypeA').jVariation({ group: 'promo_area' })
$('#promoTypeB').jVariation({ group: 'promo_area', autoHide: true })
$('#promoTypeC').jVariation({ group: 'promo_area', autoHide: true })

// add a checkbox to the control panel with a label of "Show Variation #"
// override the default .show() and .hide() with custom functions
$('p').jVariation({
	onShow: function(){ this.addClass('showMe') },
	onHide: function(){ this.removeClass() }
});
		
// creates two variations that are mutually exclusive
// chains the variations on the same object (w00t! chaining!)
// first variation adds a class ('intro') to the paragraph tag
// second varitation removes all classes on the pagagraph tag
// second variation is set to autoHide to ensure that first radio button is selected
// in both cases, onHide is set to false because onShow does all the work
$('p:eq(0)').jVariation({
	onShow: function(){ this.addClass('intro'); },
	onHide: false,
	group: "first_paragraph"
}).jVariation({
	autoHide: true,
	onShow: function(){ this.removeClass(); },
	onHide: false,
	group: "first_paragraph"
});

// creates a variation for div.wrapper
// creates a separate variation for all paragraphs inside div.wrapper
// if the user clicks to show the paragraph tags and div.wrapper is hidden, div.wrapper will be shown as well
$('div.wrapper').jVariation({ id: 'theContainingDiv' });
$('div.wrapper p').jVariation({ require: 'theContainingDiv' });

Configurable Options

All configurable options are optional. See simplified usage above for... umm... usage.

label:

It's just a string that's used as the label for the checkbox/radio button.

autoHide:

Boolean (either true or false). If autoHide is true then the HTML elements are hidden using the default .hide() or the onHide function, if provided.

onShow:

Either false, or a function. I don't see any real purpose to "false" for onShow, but I like the symmetry with onHide. If false, it is ignored. If a function, the function will be used instead of the default .show(). Note, the 'this' keyword in your function will refer to the collection of jQuery objects this variation is applied to. So 'this' in $('p').jVariation( onShow: function(){ this }); will refer to $('p')

onHide:

Either false, or a function. If false, the hiding of a variation is ignored. This is useful with radio buttons that change the class name of a single DIV when selected (shown) and should therefore do nothing when hidden. If a function is provided, the function will be used instead of the default .hide(). Note, the 'this' keyword in your function will refer to the collect of jQuery objects this variation is applied to. See onShow, and simplified examples above.

group:

A string that contains no spaces or funny characters. It is used to associate mutually exclusive variations (aka radio buttons).

id:

A string that contains no spaces or funny characters. Must be unique, if declaring more than one variation id. Used to identify a variation that other variations require.

require:

A string that contains no spaces or funny characters. Must reference the id of a variation that is required. The string can be a comma separated list of ids, should more than one variation be required... but no spaces, just commas.

Recommend Use

<!-- jQuery Core ... required for jVariations ... and you're likely using it for other things too -->
<script type="text/javascript" src="jquery.js"></script>

<!-- jVariations ... contains all variation recipes so your source HTML is otherwise untouched -->
<script type="text/javascript" src="jquery.variations.js"></script>

I recommend that you keep variation recipes contained in jquery.variations.js. That way when you want to get rid of the variations control panel, you simply delete one file... there are no other special hooks or bits you need to twiddle because it works off of your existing HTML/CSS structure and the glorious power of jQuery.

Notice of DOM Manipulation

By default, jVariations uses the .show() and .hide() methods to toggle visibility. You can override this by adding your own onShow and onHide functions as described in the documentation (see js file).

jVariations appends the control panel HTML to the BODY tag. All checkboxes and radio buttons are then placed inside the control panel. All HTML objects (DIVs, INPUTs, LABELs, H1) are appended with IDs beginning with "jvariation_" ... hopefully this does not cause any collisions. jVariations also uses a document.write(css) to add the control panel CSS.

Includes a copy of jqDnR - Minimalistic Drag'n'Resize for jQuery in the JavaScript file to allow control panel to be dragged around. I took the liberty of renaming all its functions (ex: jqVariationsDnR) to avoid naming conflicts (should you have a different version of jqDnR).

Known Issues

I used jVariations successfully on several different projects when it was originally written (in 2007). However, there are some complex use cases when mutually exclusive (radio button) variations are not toggled properly if hidden (in Safari or Internet Explorer). It does not appear on simple use-cases (like on this page). No known fix exists at this time.

Please contact me if you any questions/suggestions. brian(at)cherne(dot)net

Release History