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:   

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').click(function() {
	var destroy = $(this).text() === 'Remove';
	$(this).text(destroy ? 'Re-attach' : 'Remove');
	$('#integerRelationships').relationships(destroy ? 'destroy' : {
		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 is-relationships and are not re-processed if targeted 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.

Receive notification of a clicked icon through the onSelect callback.

Web browsers and OSs:   

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]];
var descriptions = ['Browser availability', 'Browser options'];
$('#browserRelationships').relationships({set1: browsers,
	set2: oses, links: browserLinks, description: descriptions[0],
	onSelect: function(setId, itemId, label) {
		alert('You chose ' + label + ' (' + setId + '/' + itemId + ')');
	}
});
	
var descrIndex = 0;
$('#changeDesc').click(function() {
	descrIndex = 1 - descrIndex;
	$('#browserRelationships').relationships('option',
		{description: descriptions[descrIndex]});
});

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).relationships({
	opacity: 20, // Opacity of non-matching items, percentage
	set1: {}, // Details about the first set of icons
	set2: {}, // Details about the second set of icons
	links: [], // Links between the two sets based on indexes
	description: '', // The description of the sets as a whole
	onSelect: null // Callback when an icon is selected
});

$.relationships.setDefaults(settings) // Change settings for all instances

$(selector).relationships('option', settings) // Change the instance settings
$(selector).relationships('option', name, value) // Change a single instance setting
$(selector).relationships('option', name) // Retrieve an instance setting

$(selector).relationships('destroy') // Remove the relationships functionality