jquery-imagetags

A jQuery (> 1.7.0) plugin that provides image tagging.

© Copyright 2012 by Christophe Pollet

Licensed under the MIT License http://www.opensource.org/licenses/mit-license.php

Demo

See demo 1 or demo 2

Usage

$("#container").imageTags({
  option1: value1,
  ...
});

Example

HTML markup:

<link rel="stylesheet" type="text/css" href="jquery.imagetags.css">
<script src="jquery.js"></script>
<script src="jquery.imagetags.js"></script>

<div id="container">
  <img src="picture.jpg">
</div>

Javascript, somewhere in $(function() { ... }):

$("#container").imageTags();

You're all setup! For more customization, continue reading.

Options

options are:

• enableCreation [boolean] - default: true
  If false, no tag can be created.
• enableRemoval [boolean] - default: true
  If false, tags cannot be removed.
• htmlClassPrefix [string] - default: 'jquery-imagetags-'
  The class prefix for ImageTags's HTML classes.

Public methods

After the ImageTags ($.ImageTags) initialisation through $(selector).imageTags(options), it is possible to call several methods on it using the following syntax:

$(selector).imageTags('methodName' [ , param1, [ ... ] ] );

The available methods are:

• getTags(): Array[$.ImageTags.Tag]
  Returns a list of all tags defined.
• getCurrentTag(): $.ImageTags.Tag Returns the currently created tag or null.
• finalize(): void
  Finalizes the currently created tag.
• cancel(): void
  Cancels the creation of currenty created tag.
• remove(int tagid): void
  Removes the tag given its tagid.
• enableCreation(): void
  Enables tags creation.
• disableCreation(): void
  Disables tags creation.

Events

The following events are triggered at different stage of tags creation, removal or display. Their target and this is the container.

• drawend(Event event, $.ImageTags.Tag tag)
  This event is fired when the user releases the mouse. Calling e.preventDefalut() inhibits the default action.
  Default: a Javascript prompt is displayed (see function ImageTags.Handlers.container.drawend), asking the user for a tag content. If the text is empty the tag is not created.

• tagadded(Event event, $.ImageTags.Tag tag)
  This event is fired when a tag is added (after finalize() completes). By default nothing happens.
  Default: noop

• tagremoved(Event event, $.ImageTags.Tag tag)
  This event is fired after a tag has been removed (after remove() completes). By default nothing happend.
  Default: noop

• tagshow(Event event, $.ImageTags.Tag tag)
  This event is fired when a tag is about to be displayed. Calling e.preventDefalut() inhibits the default action.
  Default: the tag's content is displayed under the tag's frame (see function ImageTags.Handlers.container.tagshow).

• taghide(Event event, $.ImageTags.Tag tag)
  This event is fired when a tag is about to be hidden. Calling e.preventDefalut() inhibits the default action.
  Default: the tag's content is hidden (see function ImageTags.Handlers.container.taghide).

Structures

$.ImageTags.Tag

• tagId(): int
  Returns the jquery-imagetags' tagId.
• finalize(): void
  Finishes the tag's creation (through a call to $.ImageTags.finalize()). Fires the tagadded event.
• cancel(): void
  Cancels the tag's creation (through a call to $.ImageTags.cancel()).
• remove(): void
  Remove the tag. Fires the tagremoved event.
• tagger(): $.ImageTags
  Returns the instance if $.ImageTags that is responsible of this particular tag.
• tagElement(): $(<a>)
  Returns the DOM element that draws the tag's frame on the picture.
• tagContent(): string
  Returns the tag's content (the text shown when the mouse is over the tag frame).
• setTagContent(string): void
  Sets the tag's content.
• tagArea(): $.ImageTags.Area
  Returns the tag's area (see $.ImageTags.Area).
• tagData(): object
  Returns arbitraty user data associated with this tag.
• setTagData(object): void
  Sets arbitrary user data associated with this tag.
• domContainer(): $(<div>)
  Returns the DOM element that contains the image and the tags (i.e. the elements returned by $(selector) when calling $.fn.imageTags() during the setup).
• domContent(): $(<div>)
  Returns the DOM element that holds the tag's content when it's displayed.
• domImage(): $(<img>)
  Returns the DOM image the tag is associated with.
• isDisplayed( [ boolean ] ): boolean, void
  Sets/Gets (depending on the presence of the boolean parameter) whether the tag should be considered as displayed by the plugin.

$.ImageTags.Area

An area stores the location where a tag is on an image. To allow for easy image resizing, two area modes are available:

1. fixed area: the corners are defined as absolute pixel positions; when the image is resized, the tags "move" relative to the their picture objects.
2. proportional area: the corners are defined as a percentage on image's height and width; when the image is resized, the tags don't move and keep their positions relative to their picure objects.

Available method are:

• $.ImageTags.Area(int, float x1, int, float y1, int, float x2, int, float y2, [ {'fixed','proportional'} mode, [ int height, int width ] ] )
  Constructor. (x1, y1) and (x2, y2) define the top-left and bottom-right corners. Mode defines the type of area, default to fixed. Height and width define the image's size, used for conversions between fixed and proportional area, see below.
• setImageSize( [ int height, int width ] )
  Sets the image size, used to translate fixed position to/from proportional ones.
• fixed( [ int height, int width ] ): object { int x1, int y1, int x2, int y2 }
  Returns the fixed position corresponding to the current area. 3 cases can occur:
  1. If the area is already using fixed poistion as internal representation (defined during object's initialization) this position is returned;
  2. If the area has an known image size it is are used to compute the fixed position, regardless of height and width parameters;
  3. Otherwise, the height and width parameters are used to do the conversion.
• toFixed( [ int height, int width ] ): $.ImageTags.Area
  Returns a new area instance corresponding to the fixed positions. The height and width parametes usage is the same as described for fixed().
• proportional( [ int height, int width ] )
  Returns the fixed position proportional to the current area. Same remarks as fixed() apply regarding the parameters.
• toProportional( [ int height, int width ] )
  Returns a new area instance corresponding to the proportional positions. Same remarks as fixed() apply regarding the parameters.