Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 188 lines (123 sloc) 5.597 kb
eb91c07 @grobie add a better Readme
grobie authored
1 # tag-it: a jQuery plugin
2
3 > After looking for a jQuery plugin for handling a 'tag suggestion' form field, in much the same way ZenDesk.com does, I ended up developing a customization of jQuery UI that does the same interaction.
4 [Levy Carneiro Jr.](http://github.com/levycarneiro)
5
6 ## Demo
7
8 ![Screenshot](http://github.com/grobie/tag-it/raw/master/screenshot.png)
9
a92e327 @grobie fix readme
grobie authored
10 Check the [example.html](http://github.com/grobie/tag-it/blob/master/example.html) for a demo.
eb91c07 @grobie add a better Readme
grobie authored
11
12 ## Usage
13
14 First, load [jQuery](http://jquery.com/), [jQuery UI](http://jqueryui.com/) and the plugin:
15
16 <script src="js/jquery/jquery-1.4.2.min.js" type="text/javascript" charset="utf-8"></script>
17 <script src="js/jquery-ui/jquery-ui-1.8.core-and-interactions.min.js" type="text/javascript" charset="utf-8"></script>
18 <script src="js/jquery-ui/jquery-ui-1.8.autocomplete.min.js" type="text/javascript" charset="utf-8"></script>
19 <script src="js/tag-it.js" type="text/javascript" charset="utf-8"></script>
20
21 Notice, to make it work under IE you have to additionally load 'js/ie-compat.js'.
22
23 <script src="js/ie-compat.js" type="text/javascript" charset="utf-8"></script>
24
25 Now, let's attach it to an existing `<ul>` box:
26
27 <script type="text/javascript">
28 $(document).ready(function() {
29 $("#mytags").tagit();
30 });
31 </script>
32
33 <ul id="mytags">
34 <!-- Existing list items will be pre-added to the tags -->
35 <li>Tag1</li>
36 <li>Tag2</li>
37 </ul>
38
39 This will turn the list into a tag-it list:
40
41 <ul id="mytags" class="tagit">
42 <!-- Existing list items will be pre-added to the tags -->
43 <li class="tagit-choice">
44 Tag1
45 <a class="close">x</a>
46 <input type="hidden" style="display:none;" value="Tag1" name="item[tags][]">
47 </li>
48 <li class="tagit-choice">
49 Tag2
50 <a class="close">x</a>
51 <input type="hidden" style="display:none;" value="Tag2" name="item[tags][]">
52 </li>
53 <li class="tagit-new">
54 <input class="tagit-input ui-autocomplete-input" type="text" autocomplete="off" role="textbox" aria-autocomplete="list" aria-haspopup="true">
55 </li>
56 </ul>
57
58 ## Options
59
60 Tag-it accepts several options to customize the behaviour:
61
62 ### itemName (String)
63
a92e327 @grobie fix readme
grobie authored
64 Used to build the name of the hidden input field: `itemName[fieldName][]`.
eb91c07 @grobie add a better Readme
grobie authored
65
66 $("#mytags").tagit({
67 itemName: "user"
68 });
69
70 Defaults to *item*.
71
72 ### fieldName (String)
73
a92e327 @grobie fix readme
grobie authored
74 Used to build the name of the hidden input field: `itemName[fieldName][]`.
eb91c07 @grobie add a better Readme
grobie authored
75
76 $("#mytags").tagit({
77 fieldName: "skills"
78 });
79
80 Defaults to *tags*.
81
82 ### availableTags (Array)
83
84 Used as source for the autocompletion.
85
86 $("#mytags").tagit({
87 availableTags: ["c++", "java", "php", "javascript", "ruby", "python", "c"]
88 });
89
90 Defaults to an empty array *[]*.
91
92 ### onTagAdded (function, Callback)
93
94 Can be used to add custom behaviour before the Tag is added to the DOM.
95 The function receives the tag as parameter.
96
97 $("#mytags").tagit({
98 onTagAdded: function(tag) {
99 // do something special
100 }
101 });
102
103 ### onTagRemoved (function, Callback)
104
105 Can be used to add custom behaviour before the Tag is removed from the DOM.
106 The function receives the tag as parameter.
107
108 $("#mytags").tagit({
a92e327 @grobie fix readme
grobie authored
109 onTagRemoved: function(tag) {
eb91c07 @grobie add a better Readme
grobie authored
110 // do something special
111 }
112 });
113
01ee739 @Yavari Added onTagClicked callback and updated the readme
Yavari authored
114 ### onTagClicked (function, Callback)
115
116 Can be used to add custom behaviour when the Tag is clicked from the DOM.
117 The function receives the tag as parameter.
118
119 $("#mytags").tagit({
120 onTagClicked: function(tag) {
121 // do something special
122 }
123 });
124
eb91c07 @grobie add a better Readme
grobie authored
125 ### tagSource (function)
126
127 Can be overwritten in order to use custom autocompletion sources like Ajax requests.
128 The default function filters the strings in **availableTags** and subtracts the already assigned tags.
129
130 ### removeConfirmation (boolean)
131
132 When removeConfirmation is enabled the user has to press the backspace key twice to remove the last tag.
133 After the first keypress the last tag receives a *remove* css class which can be used to visually highlight the tag.
134
135 Defaults to *false*.
136
01ee739 @Yavari Added onTagClicked callback and updated the readme
Yavari authored
137 ### caseSensitive (boolean)
138
139 whether the duplication check should do a case sensitive check or not.
140
141 Defaults to *true*.
142
494f729 @sskylar Updated Readme
sskylar authored
143 ### allowSpaces (boolean)
144
145 When allowSpaces is enabled the user is not required to wrap multi-word tags in quotation marks.
146 ie. user can enter John Smith instead of "John Smith"
147
148 Defaults to *false*.
149
2fd2364 @aehlke updated docs with new options
authored
150 ### singleField (boolean)
151
152 When enabled, will use a single hidden field for the form, rather than one per tag.
153 It will delimit tags in the field with **singleFieldDelimiter**.
154
155 Defaults to *false*
156
460cdcb @aehlke fixed docs
authored
157 ### singleFieldDelimiter (String)
2fd2364 @aehlke updated docs with new options
authored
158
159 Defaults to *','*
160
460cdcb @aehlke fixed docs
authored
161 ### singleFieldNode (DomNode)
2fd2364 @aehlke updated docs with new options
authored
162 Set this to an input DOM node to use an existing form field.
163 Any text in it will be erased on init. But it will be populated with the text of tags as they are created, delimited by **singleFieldDelimiter**.
164 If this is not set, we create an input node for it, with the name given in **fieldName**, ignoring **itemName**.
165
166 Defalts to *null*
167
9dc00cf @aehlke added a tabIndex option
authored
168 ### tabIndex (integer)
169 Optionally set a *tabindex* attribute on the input that gets created for tag-it.
170
171 Defaults to *null*
172
173
b78987e @aehlke updated docs to reflect new removeAll method
authored
174 ## Methods
175
176 ### removeAll()
177 Clears the widget of all tags -- removes each tag it contains, so the onTagRemoved event callback (if set in the options) will be called for each.
178
179
eb91c07 @grobie add a better Readme
grobie authored
180 ## Authors
181
182 * [Levy Carneiro Jr.](http://github.com/levycarneiro)
183 * [Martin Rehfeld](http://github.com/martinrehfeld)
184 * [Tobias Schmidt](http://github.com/grobie)
494f729 @sskylar Updated Readme
sskylar authored
185 * [Skylar Challand](http://github.com/sskylar)
10c01dd @aehlke added name to authors list
authored
186 * [Alex Ehlke](http://github.com/aehlke)
187
Something went wrong with that request. Please try again.