Back to index
|
Fork me on github
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:
- fixed area: the corners are defined as absolute pixel positions; when the image is resized, the tags "move" relative to the their picture objects.
- 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:
- If the area is already using fixed poistion as internal representation (defined during object's initialization) this position is returned;
- If the area has an known image size it is are used to compute the fixed position, regardless of height and width parameters;
- 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.