Skip to content
Newer
Older
100644 218 lines (135 sloc) 7.54 KB
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
authored
1 # Tag-it: a jQuery UI plugin
2
3 Tag-it was originally inspired by the "tag suggestion" form field in ZenDesk.com. Now it is a full jQuery UI widget, supporting various configurations and themes.
eb91c07 @grobie add a better Readme
grobie authored
4
5
6 ## Demo
7
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
authored
8 ![Screenshot](http://aehlke.github.com/tag-it/screenshot.png)
9
10 Check the [example.html](http://aehlke.github.com/tag-it/example.html) for several demos.
eb91c07 @grobie add a better Readme
grobie authored
11
12
13 ## Usage
14
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
authored
15 First, load [jQuery](http://jquery.com/) (1.5.x or greater), [jQuery UI](http://jqueryui.com/) (1.8.x or greater), and the plugin:
eb91c07 @grobie add a better Readme
grobie authored
16
3f0dc26 @aehlke update jQuery and jQuery UI
authored
17 <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.5.2/jquery.min.js" type="text/javascript" charset="utf-8"></script>
18 <script src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.8.12/jquery-ui.min.js" type="text/javascript" charset="utf-8"></script>
eb91c07 @grobie add a better Readme
grobie authored
19 <script src="js/tag-it.js" type="text/javascript" charset="utf-8"></script>
20
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
authored
21 The plugin requires a jQuery UI theme to be present, as well as its own included base CSS file ([jquery.tagit.css](http://github.com/aehlke/tag-it/raw/master/css/jquery.tagit.css). Here we use the Flick theme as an example:
eb91c07 @grobie add a better Readme
grobie authored
22
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
authored
23 <link rel="stylesheet" type="text/css" href="http://ajax.googleapis.com/ajax/libs/jqueryui/1/themes/flick/jquery-ui.css">
24 <link href="css/jquery.tagit.css" rel="stylesheet" type="text/css">
eb91c07 @grobie add a better Readme
grobie authored
25
26 Now, let's attach it to an existing `<ul>` box:
27
28 <script type="text/javascript">
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
authored
29 $(document).ready(function() {
30 $("#mytags").tagit();
31 });
eb91c07 @grobie add a better Readme
grobie authored
32 </script>
33
34 <ul id="mytags">
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
authored
35 <!-- Existing list items will be pre-added to the tags -->
36 <li>Tag1</li>
37 <li>Tag2</li>
eb91c07 @grobie add a better Readme
grobie authored
38 </ul>
39
40 This will turn the list into a tag-it list:
41
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
authored
42 <ul id="mytags" class="tagit ui-widget ui-widget-content ui-corner-all">
43 <!-- Existing list items will be pre-added to the tags. -->
44 <li class="tagit-choice ui-widget-content ui-state-default ui-corner-all">
45 <span class="tagit-label">Tag1</span>
46 <a class="close"><span class="ui-icon ui-icon-close"></span></a>
47 <input type="hidden" style="display:none;" value="Tag1" name="item[tags][]">
48 </li>
49 <li class="tagit-choice ui-widget-content ui-state-default ui-corner-all">
50 <span class="tagit-label">Tag2</span>
51 <a class="close"><span class="ui-icon ui-icon-close"></span></a>
52 <input type="hidden" style="display:none;" value="Tag2" name="item[tags][]">
53 </li>
54 <li class="tagit-new">
55 <input type="text" class="ui-widget-content ui-autocomplete-input" autocomplete="off" role="textbox" aria-autocomplete="list" aria-haspopup="true">
56 </li>
eb91c07 @grobie add a better Readme
grobie authored
57 </ul>
58
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
authored
59 There are several other possible configurations and ways to instantiate the widget, including one that uses a single comma-delimited `input` field rather than one per tag, so see the **Options** documentation below as well as the [examples page](http://aehlke.github.com/tag-it/example.html) which demonstrates most of them.
60
61
62 ## Theming
63
64 Tag-it is as easily themeable as any jQuery UI widget, using your own theme made with [Themeroller](http://jqueryui.com/themeroller/), or one of the jQuery UI [premade themes](http://jqueryui.com/themeroller/#themeGallery). The old ZenDesk-like theme is included as an optional CSS file ([tagit.ui-zendesk.css](http://github.com/aehlke/tag-it/raw/master/css/tagit.ui-zendesk.css)).
65
66
eb91c07 @grobie add a better Readme
grobie authored
67 ## Options
68
69 Tag-it accepts several options to customize the behaviour:
70
71 ### itemName (String)
72
a92e327 @grobie fix readme
grobie authored
73 Used to build the name of the hidden input field: `itemName[fieldName][]`.
eb91c07 @grobie add a better Readme
grobie authored
74
75 $("#mytags").tagit({
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
authored
76 itemName: "user"
eb91c07 @grobie add a better Readme
grobie authored
77 });
78
79 Defaults to *item*.
80
81 ### fieldName (String)
82
a92e327 @grobie fix readme
grobie authored
83 Used to build the name of the hidden input field: `itemName[fieldName][]`.
eb91c07 @grobie add a better Readme
grobie authored
84
85 $("#mytags").tagit({
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
authored
86 fieldName: "skills"
eb91c07 @grobie add a better Readme
grobie authored
87 });
88
89 Defaults to *tags*.
90
91 ### availableTags (Array)
92
93 Used as source for the autocompletion.
94
95 $("#mytags").tagit({
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
authored
96 availableTags: ["c++", "java", "php", "javascript", "ruby", "python", "c"]
eb91c07 @grobie add a better Readme
grobie authored
97 });
98
99 Defaults to an empty array *[]*.
100
101 ### tagSource (function)
102
103 Can be overwritten in order to use custom autocompletion sources like Ajax requests.
104 The default function filters the strings in **availableTags** and subtracts the already assigned tags.
105
106 ### removeConfirmation (boolean)
107
108 When removeConfirmation is enabled the user has to press the backspace key twice to remove the last tag.
109 After the first keypress the last tag receives a *remove* css class which can be used to visually highlight the tag.
110
111 Defaults to *false*.
112
01ee739 @Yavari Added onTagClicked callback and updated the readme
Yavari authored
113 ### caseSensitive (boolean)
114
115 whether the duplication check should do a case sensitive check or not.
116
117 Defaults to *true*.
118
494f729 @sskylar Updated Readme
sskylar authored
119 ### allowSpaces (boolean)
120
121 When allowSpaces is enabled the user is not required to wrap multi-word tags in quotation marks.
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
authored
122 For example, the user can enter `John Smith` instead of `"John Smith"`.
494f729 @sskylar Updated Readme
sskylar authored
123
124 Defaults to *false*.
125
2fd2364 @aehlke updated docs with new options
authored
126 ### singleField (boolean)
127
128 When enabled, will use a single hidden field for the form, rather than one per tag.
129 It will delimit tags in the field with **singleFieldDelimiter**.
130
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
authored
131 Defaults to *false*, unless Tag-it was created on an `input` element, in which case **singleField** will be overridden as true.
2fd2364 @aehlke updated docs with new options
authored
132
460cdcb @aehlke fixed docs
authored
133 ### singleFieldDelimiter (String)
2fd2364 @aehlke updated docs with new options
authored
134
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
authored
135 Defaults to *","*
2fd2364 @aehlke updated docs with new options
authored
136
460cdcb @aehlke fixed docs
authored
137 ### singleFieldNode (DomNode)
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
authored
138
2fd2364 @aehlke updated docs with new options
authored
139 Set this to an input DOM node to use an existing form field.
140 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**.
141 If this is not set, we create an input node for it, with the name given in **fieldName**, ignoring **itemName**.
142
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
authored
143 Defaults to *null*, unless Tag-it was created on an `input` element, in which case **singleFieldNode** will be overridden with that element.
2fd2364 @aehlke updated docs with new options
authored
144
9dc00cf @aehlke added a tabIndex option
authored
145 ### tabIndex (integer)
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
authored
146 Optionally set a *tabindex* attribute on the `input` that gets created for tag-it user input.
9dc00cf @aehlke added a tabIndex option
authored
147
148 Defaults to *null*
149
150
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
authored
151 ## Events
152
153 ### onTagAdded (function, Callback)
154
155 Can be used to add custom behaviour before the Tag is added to the DOM.
156 The function receives an empty event, and the tag as parameters.
157
158 $("#mytags").tagit({
159 onTagAdded: function(event, tag) {
160 // do something special
161 }
162 });
163
164 ### onTagRemoved (function, Callback)
165
166 Can be used to add custom behaviour before the Tag is removed from the DOM.
167 The function receives an empty event, and the tag as parameters.
168
169 $("#mytags").tagit({
170 onTagRemoved: function(event, tag) {
171 // do something special
172 }
173 });
174
175 ### onTagClicked (function, Callback)
176
177 Can be used to add custom behaviour when the Tag is clicked from the DOM.
178 The function receives the click event and the tag as parameters.
179
180 $("#mytags").tagit({
181 onTagClicked: function(event, tag) {
182 // do something special
183 }
184 });
185
186
b78987e @aehlke updated docs to reflect new removeAll method
authored
187 ## Methods
188
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
authored
189 ### assignedTags()
190 Returns an array of the text values of all the tags currently in the widget.
191
192 $("#mytags").tagit("assignedTags");
b78987e @aehlke updated docs to reflect new removeAll method
authored
193
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
authored
194 ### createTag(tagName, additionalClass)
195 Adds new tag to the list. The `additionalClass` parameter is an optional way to add classes to the tag element.
88d1771 @aehlke added removeAll example usage to docs
authored
196
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
authored
197 $("#mytags").tagit("createTag", "brand-new-tag");
198
199 ### removeAll()
200 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.
1c73ae4 @Nabuchodonozor added createTag() method to readme
Nabuchodonozor authored
201
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
authored
202 $("#mytags").tagit("removeAll");
1c73ae4 @Nabuchodonozor added createTag() method to readme
Nabuchodonozor authored
203
b78987e @aehlke updated docs to reflect new removeAll method
authored
204
eb91c07 @grobie add a better Readme
grobie authored
205 ## Authors
206
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
authored
207 * [Levy Carneiro Jr.](http://github.com/levycarneiro) *original author*
eb91c07 @grobie add a better Readme
grobie authored
208 * [Martin Rehfeld](http://github.com/martinrehfeld)
209 * [Tobias Schmidt](http://github.com/grobie)
494f729 @sskylar Updated Readme
sskylar authored
210 * [Skylar Challand](http://github.com/sskylar)
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
authored
211 * [Alex Ehlke](http://github.com/aehlke) *current maintainer*
ee7481f @aehlke merge in MIT license from original author repo
authored
212
213
214 ## License
215
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
authored
216 tag-it is released under the [MIT license](http://github.com/aehlke/tag-it/raw/master/LICENSE).
ee7481f @aehlke merge in MIT license from original author repo
authored
217
Something went wrong with that request. Please try again.