Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 223 lines (138 sloc) 7.866 kB
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
aehlke 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
aehlke authored
8 ![Screenshot](http://aehlke.github.com/tag-it/screenshot.png)
9
6fad702 Point to actual file instead of raw source.
Tim Jarratt authored
10 Check the [examples.html](http://aehlke.github.com/tag-it/examples.html) for several demos.
eb91c07 @grobie add a better Readme
grobie authored
11
12
13 ## Usage
14
fb09577 @aehlke add copyright and versioning info
aehlke authored
15 First, load [jQuery](http://jquery.com/) (v1.4 or greater), [jQuery UI](http://jqueryui.com/) (v1.8 or greater), and the plugin:
eb91c07 @grobie add a better Readme
grobie authored
16
3f0dc26 @aehlke update jQuery and jQuery UI
aehlke 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
09d5dc3 @aehlke fix docs typo
aehlke 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
aehlke 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
aehlke 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
aehlke 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
aehlke 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
1a76a00 @aehlke update link to new example filename
aehlke 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/examples.html) which demonstrates most of them.
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
aehlke authored
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
aehlke 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
aehlke 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
aehlke 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
aehlke 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
aehlke 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
aehlke 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
aehlke authored
132
460cdcb @aehlke fixed docs
aehlke authored
133 ### singleFieldDelimiter (String)
2fd2364 @aehlke updated docs with new options
aehlke authored
134
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
aehlke authored
135 Defaults to *","*
2fd2364 @aehlke updated docs with new options
aehlke authored
136
460cdcb @aehlke fixed docs
aehlke authored
137 ### singleFieldNode (DomNode)
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
aehlke authored
138
2fd2364 @aehlke updated docs with new options
aehlke 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
aehlke 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
aehlke authored
144
9dc00cf @aehlke added a tabIndex option
aehlke authored
145 ### tabIndex (integer)
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
aehlke authored
146 Optionally set a *tabindex* attribute on the `input` that gets created for tag-it user input.
9dc00cf @aehlke added a tabIndex option
aehlke authored
147
148 Defaults to *null*
149
a877af5 add a param for placeholder text on the automatically created input e…
Ben Oberkfell authored
150 ### placeholderText (String)
151 Optionally set a *placeholder* attribute on the `input` that gets created for tag-it user input.
152
153 Defaults to *null*
154
9dc00cf @aehlke added a tabIndex option
aehlke authored
155
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
aehlke authored
156 ## Events
157
158 ### onTagAdded (function, Callback)
159
160 Can be used to add custom behaviour before the Tag is added to the DOM.
161 The function receives an empty event, and the tag as parameters.
162
163 $("#mytags").tagit({
164 onTagAdded: function(event, tag) {
165 // do something special
166 }
167 });
168
169 ### onTagRemoved (function, Callback)
170
171 Can be used to add custom behaviour before the Tag is removed from the DOM.
172 The function receives an empty event, and the tag as parameters.
173
174 $("#mytags").tagit({
175 onTagRemoved: function(event, tag) {
176 // do something special
177 }
178 });
179
180 ### onTagClicked (function, Callback)
181
182 Can be used to add custom behaviour when the Tag is clicked from the DOM.
183 The function receives the click event and the tag as parameters.
184
185 $("#mytags").tagit({
186 onTagClicked: function(event, tag) {
187 // do something special
188 }
189 });
190
191
b78987e @aehlke updated docs to reflect new removeAll method
aehlke authored
192 ## Methods
193
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
aehlke authored
194 ### assignedTags()
195 Returns an array of the text values of all the tags currently in the widget.
196
197 $("#mytags").tagit("assignedTags");
b78987e @aehlke updated docs to reflect new removeAll method
aehlke authored
198
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
aehlke authored
199 ### createTag(tagName, additionalClass)
200 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
aehlke authored
201
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
aehlke authored
202 $("#mytags").tagit("createTag", "brand-new-tag");
203
204 ### removeAll()
205 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
206
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
aehlke authored
207 $("#mytags").tagit("removeAll");
1c73ae4 @Nabuchodonozor added createTag() method to readme
Nabuchodonozor authored
208
b78987e @aehlke updated docs to reflect new removeAll method
aehlke authored
209
eb91c07 @grobie add a better Readme
grobie authored
210 ## Authors
211
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
aehlke authored
212 * [Levy Carneiro Jr.](http://github.com/levycarneiro) *original author*
eb91c07 @grobie add a better Readme
grobie authored
213 * [Martin Rehfeld](http://github.com/martinrehfeld)
214 * [Tobias Schmidt](http://github.com/grobie)
494f729 @sskylar Updated Readme
sskylar authored
215 * [Skylar Challand](http://github.com/sskylar)
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
aehlke authored
216 * [Alex Ehlke](http://github.com/aehlke) *current maintainer*
ee7481f @aehlke merge in MIT license from original author repo
aehlke authored
217
218
219 ## License
220
07a7a73 @aehlke general progress on cleanup and jQ UI compliance
aehlke authored
221 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
aehlke authored
222
Something went wrong with that request. Please try again.