jQuery Relationships

Introduction

The relationships functionality can easily be added to a div or span. It displays two sets of icons and the many-to-many relationships between them. Hovering over an icon dims the others in that set and highlights the items from the other set that correspond to it. You can also remove the relationships widget if it is no longer required.

The example here shows the numbers from 1 to 4 and categorises them as odd, even, and/or prime.

Integer Relationships:   Remove

var integers = {images: 'img/integers.png', imageSize: [25, 29],
	items: ['Number one', 'Number two', 'Number three', 'Number four']};
var intTypes = {images: 'img/intTypes.png', imageSize: [27, 27],
	items: ['Odd numbers', 'Even numbers', 'Prime numbers']};
var intLinks = [[0, 0], [1, 1], [1, 2], [2, 0], [2, 2], [3, 1]];
$('#integerRelationships').relationships({set1: integers,
	set2: intTypes, links: intLinks, description: 'Integers'});

$('#removeRelationships').toggle(
	function() {
		$(this).text('Re-attach');
		$('#integerRelationships').relationships('destroy');
	},
	function() {
		$(this).text('Remove');
		$('#integerRelationships').relationships({set1: integers,
			set2: intTypes, links: intLinks, description: 'Integers'});
	}
);

You can override the defaults globally as shown below:

$.relationships.setDefaults({opacity: 20});

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

Browsers Example

As another example you can show which Web browsers are available on which operating systems.

Note that you can override the default index into the image by specifying items as objects with attributes description and imageIndex.

Web browsers and OSs:   Change description

var browsers = {images: 'img/logos.png', imageSize: [32, 32],
	items: ['Internet Explorer', 'Firefox', 'Safari', 'Opera', 'Netscape']};
var oses = {images: 'img/logos.png', imageSize: [32, 32],
	items: [{description: 'Windows', imageIndex: 6},
	{description: 'Mac', imageIndex: 7},
	{description: 'Linux', imageIndex: 8}]};
var browserLinks = [[0, 0], [1, 0], [1, 1], [1, 2], [2, 0], [2, 1],
	[3, 0], [3, 1], [3, 2], [4, 0], [4, 1], [4, 2]];
$('#browserRelationships').relationships({set1: browsers,
	set2: oses, links: browserLinks, description: 'Browser availability'});
	
$('#changeDesc').toggle(
	function() {
		$('#browserRelationships').relationships('change',
			{description: 'Browser options'});
	},
	function() {
		$('#browserRelationships').relationships('change',
			{description: 'Browser availability'});
	}
);

Backwards Compatibility

Several interface changes were made between v1.0 and v1.1 to bring the plugin into line with the new UI interface standards.

To assist in the upgrade process, a compatibility module is available that allows a v1.0 page to be run against the latest code.

Just add the following line to your page after the plugin load to continue running:

<script type="text/javascript" src="jquery.relationships.compat-1.0.js"></script>

To complete the upgrade perform the following steps:

• Replace $(…).attachRelationships(…) with $(…).relationships(…)
• Replace $(…).changeRelationships(…) with $(…).relationships('change', …)
• Replace $(…).removeRelationships() with $(…).relationships('destroy')

In the Wild

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

To add another example, please contact me (kbwood{at}iinet.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).relationships({
	opacity: 20, // Opacity of non-matching items, percentage
	// Details about the first set of icons
	set1: {images: 'integers.png', imageSize: [25, 29],	
		items: ['Number one', 'Number two', ...]},
	// Details about the second set of icons
	set2: {images: 'intTypes.png', imageSize: [27, 27], 
		items: ['Odd numbers', 'Even numbers', ...]};
	// Links between the two sets based on indexes
	links: [[0, 0], [1, 1], [1, 2], [2, 0], [2, 2], [3, 1]], 
	description: 'Integers' // The description of the sets as a whole
});