README.md

taggd

A configurable jQuery plugin that allows you to tag images with pulse effect.

1. Installation

Download the archive or browse the repository.

Then include it after your jQuery file.

<script src="js/jquery.js"></script>
<script src="js/jquery.taggd.js"></script>

Optionally you can use include (and edit) the css file as well.

<link href="css/taggd.css" />

2. Configuration

var options = {
	
	// Aligning the text popups
	align: {
		x: 'center', // left, center or right
		y: 'center'	// top,	center or bottom
	},
	
	
	// The (relative) offset of the popups in pixels
	offset: {
		left: 0, // horizontal offset
		top: 12	// vertical offset
	},
	
	
	// event handlers of the tags
	handlers: {
	
		// Any vanilla JavaScript event is a valid key
		click: function(e) {
			alert('You clicked a button');

			this; // the DOM Node
			e;	// the Event
		},
	
	
		// For convenience, you can use strings to
		// show, hide and toggle the popups
		mouseenter: 'show',
		mouseleave: 'hide'
	}
	
	// Whether to enable editor mode
	edit: false,
	
	// Strings for buttons
	strings: {
		save: '✓',
		delete: '×'
	}
};


// The magic comes together here
$('.taggd').taggd( options, data );

3. What is “data” and how do I get it?

Data are the tags. Taggd accepts different formats, so pay close attention!

var data = [
	// x and y values can be decimals (0-1)
	{
		x: 0.512,
		y: 0.33,
		
		// (Optional) Set the text of the popup.
		// If omitted, no popup window will appear.
		text: 'Huey',
		
		// (Optional) Set the element’s attributes.
		attributes: {
			id:    'my-id',
			class: 'my-class'
		}
	},
	
	// x and y values can be in pixels too
	// Don’t you worry, they will scale perfectly
	{
		x: 1052,
		y: 356,
		text: 'Duwey'
	}
];

As noted in the comments, whatever unit you use, they will scale. The coordinates are always right.

Not sure how to get them? Use generator to get coordinates.

4. The API

But other than putting in data, you can do more with Taggd!

Managing data

// Replace existing data with new data
taggd.setData( [ ... ] );

// Add new items
taggd.addData( { ... } );            // one item or
taggd.addData( [{ ... }, { ... }] ); // multiple items

// Get rid of all the tags
taggd.clear();

// Undo everthing Taggd did
taggd.dispose();

Show/hide/toggle tags

// Show/hide/toggle all items
taggd.show();
taggd.hide();
taggd.toggle();

These three methods all accept the following arguments.

// A specific index
taggd.show( 1 );

// A CSS selector
taggd.show( '#el-one, :nth-child(1)' );

// A jQuery element
taggd.show( $('#el-two') );

// An array containing any of the formats above
taggd.show( ['#el-one', 1] );

// A function that returns true or false
taggd.show(function(i, e) {
	
	// Show if tag contains a search query
	return data[i].text.indexOf(search_query);
	
});

These methods can be chained.

taggd.hide().show( 1 );

For examples and styled documentation, visit the project page.