jQuery Tag Handler v2.0.0-alpha
Copyright (C) 2010-2011 Mark Jubenville
Mark Jubenville - [email protected]
http://ioncache.github.com/Tag-Handler

Development time supported by:
Raybec Communications
http://www.raybec.com
http://www.mysaleslink.com

Modified by Javier Fernandez Escribano - [email protected]
Added autocomplete queries as the user writes

Development time supported by:
Tourist Eye
http://www.touristeye.com

Modified By Westin Shafer - [email protected]
Code re-write.  Added new features.

Development time supported by:
Reliv International
http://www.reliv.com

Based heavily on:
Tag it! by Levy Carneiro Jr (http://levycarneiro.com/)
http://levycarneiro.com/projects/tag-it/example.html
http://github.com/levycarneiro/tag-it
http://plugins.jquery.com/project/tag-it

Tag icons/cursors converted from:
From the famfamfam.com Silk icon set:
http://www.famfamfam.com/lab/icons/silk/

Loader image created at:
Preloaders.net
http://preloaders.net/

------------------------------------------------------------------------------
Description
------------------------------------------------------------------------------

Tag Handler is a jQuery plugin used for managing tag-type metadata.

------------------------------------------------------------------------------
Basic Usage Instructions
------------------------------------------------------------------------------

* Tag Handler must be attached to one or more <ul> tags in your HTML.

* To add a tag, click on the tag box, type in a name, and hit enter or comma.

* Tags may be removed from the tag box by hitting backspace inside the box or
by clicking on the tag.

* The list of tags may be initialized in 1 of 3 ways:

1. By passing arrays of tag names as options to the plugin
("availableTags" and "assignedTags"); or,

2. By supplying a "getURL" for the tags to be retrieved via AJAX.

When using this method, the server must supply a JSON formatted array
named "availableTags" and optionally an additional array named
"assignedTags".

3. By supplying a "getURL" and initLoad: false.

When using this method, it will get the "assignedTags" from the array as in
method 1. When the user writes a tag, it will query the server searching for
similar tags.

Either way, the information from these 3 methods will be used in the
following manner:

availableTags: each item in this array will populate the autocomplete
drop-down list

assignedTags: each item this array will become a tag in the tag box

* Tags may be sent back to the server by supplying an "updateURL". In this case,
an array will be sent back to the server named "tags".

* You can define whether the user can create new tags or select tags only.

* You can define if the user can edit the tags.

* A sample CSS file is included that can be used to help with formatting tags.

------------------------------------------------------------------------------
Plugin Examples
------------------------------------------------------------------------------

Example 1: The Tag Handler will be initialized with no options and no default
tags:

$("#basic_tag_handler").tagHandler();

Example 2: The Tag Handler will be initialized with preset tags from the
assignedTags and availableTags arrays, and autocomplete will be
turned on:

$("#array_tag_handler").tagHandler({
    assignedTags: [ 'Perl' ],
    availableTags: [ 'C', 'C++', 'C#', 'Java', 'Perl', 'PHP', 'Python' ],
    autocomplete: true
});

See http://ioncache.github.com/Tag-Handler for more examples

------------------------------------------------------------------------------
Plugin Options
------------------------------------------------------------------------------

Tag data specific options:
--------------------------

Option          Description                                     Default Value
--------------  ----------------------------------------------  --------------
assignedTags    array to pass a list of already assigned tags   []
availableTags   array to pass a list of all available tags      []
getData         data field with info for getURL                 ''
getURL          URL for retrieving tag lists via ajax           {}
initLoad        indicates if all tags should be loaded on init  true
updateData      data field with additional info for updtateURL  {}
updateURL       URL for saving tags via ajax                    ''

Callback options:
-----------------
Option          Description                                     Default Value
--------------  ----------------------------------------------  --------------
onAdd           function to be called when a new tag is added   {}
onDelete        function to be called when a tag is deleted     {}
afterAdd        function to be called after a new tag is added  {}
afterDelete     function to be called after a tag is deleted    {}
onIsValid       funciton to be called during validation         {}
afterLoad       funciton to be called once loaded               {}

Miscellaneous options:
----------------------

Option          Description                                     Default Value
--------------  ----------------------------------------------  --------------
allowAdd        indicates whether the user can add new tags     true
allowEdit       indicates whether the tag list is editable      true
autocomplete    requires jqueryui autocomplete plugin           false
autoUpdate      indicates whether updating occurs automatically false
                whenever a tag is added/deleted - if set true,
                the save button will not be shown
className       base class name that will be added to the tag   'tagHandler'
                container
debug           will turn on some console logging debug info    false
delimiter       extra delimiter to use to separate tags         ''
                note 'enter' and 'comma' are always allowed
maxTags         sets a limit to the number of allowed tags, set 0
                to 0 to allow unlimited
minChars        minimum number of chars to type before starting 0
                autocomplete
msgError        message shown when there is an error loading    'There was an
                the tags                                        error getting
                the tag list.'
msgNoNewTag     message shown when the user cannot add a new    'You don't have
                tag                                             permission to
                                                                create a new
                                                                tag.'
queryname       query term used to send user typed data         'q'
sortTags        sets sorting of tag names alphabetically        true
jqueryTheme     use Jquery UI ThemeRoller                       false


Methods
----------------------

Name                 Description               Usage
-------------------  -----------------------  --------------------------------
getTags              returns an array of tags .tagHandler("getTags")
getSerializedTags    returns comma separated  .tagHandler("getSerializedTags")
                     string of tags
getOptions           returns an array of all  .tagHandler("getOptions")
                     tags, both active and
                     available
getSerializedOptions returns comma separated  .tagHandler("getSerializedTags")
                     string of all tags,
                     both active and
                     available
addTag               add a new tag            .tagHandler("addTag", "my new tag")
removeTag            removes an active tag    .tagHandler("removeTag", "tag")
                     and adds it to the
                     available tags
addOption            adds a new tag to the    .tagHandler("addOption", "my new tag")
                     list of available tags

removeOption         removes a tag from the   .tagHandler("removeOption", "tag")
                     list of available tags
saveTags             force a save of the      .tagHandler("saveTags")
                     current active tags.
                     only useful if using
                     ajax to save new tags
destroy              destroy the current      .tagHandler("destroy")
                     taghandler and return
                     selector to its previous
                     state.
reload               reinitialize the         .tagHandler("reload")
                     tagHandler.  Will remove
                     any changes made to the
                     active tagHandler and
                     reload the tagHandler


------------------------------------------------------------------------------
License
------------------------------------------------------------------------------

This program is free software: you can redistribute it and/or modify
it under the terms of the Lesser GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
Lesser GNU General Public License for more details.

You should have received a copy of the Lesser GNU General Public License
along with this program.  If not, see < http://www.gnu.org/licenses/ >.