general progress on cleanup and jQ UI compliance

add some more examples allow specially instantiating the widget on INPUT, UL, or OL to prefill tag data from what exists in the markup, and set singleField in the case of INPUT make events jQuery UI-compliant fix and tweak theme and base CSS clean up JS clean up docs
wolfgang1791 · Jun 13, 2011 · 07a7a73 · 07a7a73
1 parent 1c90239
commit 07a7a73
Show file tree

Hide file tree

Showing 9 changed files with 647 additions and 293 deletions.
diff --git a/README.markdown b/README.markdown
@@ -1,59 +1,69 @@
-# tag-it: a jQuery plugin
+# Tag-it: a jQuery UI plugin
+
+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.
 
-> 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.
-[Levy Carneiro Jr.](http://github.com/levycarneiro)
 
 ## Demo
 
-![Screenshot](http://github.com/grobie/tag-it/raw/master/screenshot.png)
+![Screenshot](http://aehlke.github.com/tag-it/screenshot.png)
+
+Check the [example.html](http://aehlke.github.com/tag-it/example.html) for several demos.
 
-Check the [example.html](http://github.com/grobie/tag-it/blob/master/example.html) for a demo.
 
 ## Usage
 
-First, load [jQuery](http://jquery.com/), [jQuery UI](http://jqueryui.com/) and the plugin:
+First, load [jQuery](http://jquery.com/) (1.5.x or greater), [jQuery UI](http://jqueryui.com/) (1.8.x or greater), and the plugin:
 
     <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.5.2/jquery.min.js" type="text/javascript" charset="utf-8"></script>
     <script src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.8.12/jquery-ui.min.js" type="text/javascript" charset="utf-8"></script>
     <script src="js/tag-it.js" type="text/javascript" charset="utf-8"></script>
 
-Notice, to make it work under IE you have to additionally load 'js/ie-compat.js'.
+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:
 
-    <script src="js/ie-compat.js" type="text/javascript" charset="utf-8"></script>
+    <link rel="stylesheet" type="text/css" href="http://ajax.googleapis.com/ajax/libs/jqueryui/1/themes/flick/jquery-ui.css">
+	<link href="css/jquery.tagit.css" rel="stylesheet" type="text/css">
 
 Now, let's attach it to an existing `<ul>` box:
 
     <script type="text/javascript">
-      $(document).ready(function() {
-        $("#mytags").tagit();
-      });
+        $(document).ready(function() {
+            $("#mytags").tagit();
+        });
     </script>
 
     <ul id="mytags">
-      <!-- Existing list items will be pre-added to the tags -->
-      <li>Tag1</li>
-      <li>Tag2</li>
+        <!-- Existing list items will be pre-added to the tags -->
+        <li>Tag1</li>
+        <li>Tag2</li>
     </ul>
 
 This will turn the list into a tag-it list:
 
-    <ul id="mytags" class="tagit">
-      <!-- Existing list items will be pre-added to the tags -->
-      <li class="tagit-choice">
-        Tag1
-        <a class="close">x</a>
-        <input type="hidden" style="display:none;" value="Tag1" name="item[tags][]">
-      </li>
-      <li class="tagit-choice">
-        Tag2
-        <a class="close">x</a>
-        <input type="hidden" style="display:none;" value="Tag2" name="item[tags][]">
-      </li>
-      <li class="tagit-new">
-        <input class="tagit-input ui-autocomplete-input" type="text" autocomplete="off" role="textbox" aria-autocomplete="list" aria-haspopup="true">
-      </li>
+    <ul id="mytags" class="tagit ui-widget ui-widget-content ui-corner-all">
+        <!-- Existing list items will be pre-added to the tags. -->
+        <li class="tagit-choice ui-widget-content ui-state-default ui-corner-all">
+            <span class="tagit-label">Tag1</span>
+            <a class="close"><span class="ui-icon ui-icon-close"></span></a>
+            <input type="hidden" style="display:none;" value="Tag1" name="item[tags][]">
+        </li>
+        <li class="tagit-choice ui-widget-content ui-state-default ui-corner-all">
+            <span class="tagit-label">Tag2</span>
+            <a class="close"><span class="ui-icon ui-icon-close"></span></a>
+            <input type="hidden" style="display:none;" value="Tag2" name="item[tags][]">
+        </li>
+        <li class="tagit-new">
+            <input type="text" class="ui-widget-content ui-autocomplete-input" autocomplete="off" role="textbox" aria-autocomplete="list" aria-haspopup="true">
+        </li>
     </ul>
 
+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.
+
+
+## Theming
+
+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)).
+
+
 ## Options
 
 Tag-it accepts several options to customize the behaviour:
@@ -63,7 +73,7 @@ Tag-it accepts several options to customize the behaviour:
 Used to build the name of the hidden input field: `itemName[fieldName][]`.
 
     $("#mytags").tagit({
-      itemName: "user"
+        itemName: "user"
     });
 
 Defaults to *item*.
@@ -73,7 +83,7 @@ Defaults to *item*.
 Used to build the name of the hidden input field: `itemName[fieldName][]`.
 
     $("#mytags").tagit({
-      fieldName: "skills"
+        fieldName: "skills"
     });
 
 Defaults to *tags*.
@@ -83,44 +93,11 @@ Defaults to *tags*.
 Used as source for the autocompletion.
 
     $("#mytags").tagit({
-      availableTags: ["c++", "java", "php", "javascript", "ruby", "python", "c"]
+        availableTags: ["c++", "java", "php", "javascript", "ruby", "python", "c"]
     });
 
 Defaults to an empty array *[]*.
 
-### onTagAdded (function, Callback)
-
-Can be used to add custom behaviour before the Tag is added to the DOM.
-The function receives the tag as parameter.
-
-    $("#mytags").tagit({
-      onTagAdded: function(tag) {
-        // do something special
-      }
-    });
-
-### onTagRemoved (function, Callback)
-
-Can be used to add custom behaviour before the Tag is removed from the DOM.
-The function receives the tag as parameter.
-
-    $("#mytags").tagit({
-      onTagRemoved: function(tag) {
-        // do something special
-      }
-    });
-
-### onTagClicked (function, Callback)
-
-Can be used to add custom behaviour when the Tag is clicked from the DOM.
-The function receives the tag as parameter.
-
-    $("#mytags").tagit({
-      onTagClicked: function(tag) {
-        // do something special
-      }
-    });
-
 ### tagSource (function)
 
 Can be overwritten in order to use custom autocompletion sources like Ajax requests.
@@ -142,7 +119,7 @@ Defaults to *true*.
 ### allowSpaces (boolean)
 
 When allowSpaces is enabled the user is not required to wrap multi-word tags in quotation marks.
-ie. user can enter John Smith instead of "John Smith"
+For example, the user can enter `John Smith` instead of `"John Smith"`.
 
 Defaults to *false*.
 
@@ -151,48 +128,90 @@ Defaults to *false*.
 When enabled, will use a single hidden field for the form, rather than one per tag.
 It will delimit tags in the field with **singleFieldDelimiter**.
 
-Defaults to *false*
+Defaults to *false*, unless Tag-it was created on an `input` element, in which case **singleField** will be overridden as true.
 
 ### singleFieldDelimiter (String)
 
-Defaults to *','*
+Defaults to *","*
 
 ### singleFieldNode (DomNode)
+
 Set this to an input DOM node to use an existing form field.
 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**.
 If this is not set, we create an input node for it, with the name given in **fieldName**, ignoring **itemName**.
 
-Defalts to *null*
+Defaults to *null*, unless Tag-it was created on an `input` element, in which case **singleFieldNode** will be overridden with that element.
 
 ### tabIndex (integer)
-Optionally set a *tabindex* attribute on the input that gets created for tag-it.
+Optionally set a *tabindex* attribute on the `input` that gets created for tag-it user input.
 
 Defaults to *null*
 
 
+## Events
+
+### onTagAdded (function, Callback)
+
+Can be used to add custom behaviour before the Tag is added to the DOM.
+The function receives an empty event, and the tag as parameters.
+
+    $("#mytags").tagit({
+        onTagAdded: function(event, tag) {
+            // do something special
+        }
+    });
+
+### onTagRemoved (function, Callback)
+
+Can be used to add custom behaviour before the Tag is removed from the DOM.
+The function receives an empty event, and the tag as parameters.
+
+    $("#mytags").tagit({
+        onTagRemoved: function(event, tag) {
+            // do something special
+        }
+    });
+
+### onTagClicked (function, Callback)
+
+Can be used to add custom behaviour when the Tag is clicked from the DOM.
+The function receives the click event and the tag as parameters.
+
+    $("#mytags").tagit({
+        onTagClicked: function(event, tag) {
+            // do something special
+        }
+    });
+
+
 ## Methods
 
-### removeAll()
-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.
+### assignedTags()
+Returns an array of the text values of all the tags currently in the widget.
+
+    $("#mytags").tagit("assignedTags");
 
-    $("#mytags").tagit('removeAll');
+### createTag(tagName, additionalClass)
+Adds new tag to the list. The `additionalClass` parameter is an optional way to add classes to the tag element.
 
-### createTag(tagName)
-Adds new tag to the list.
+    $("#mytags").tagit("createTag", "brand-new-tag");
+
+### removeAll()
+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.
 
-    $("#mytags").tagit('createTag', 'brandNewTag');
+    $("#mytags").tagit("removeAll");
 
 
 ## Authors
 
-* [Levy Carneiro Jr.](http://github.com/levycarneiro)
+* [Levy Carneiro Jr.](http://github.com/levycarneiro) *original author*
 * [Martin Rehfeld](http://github.com/martinrehfeld)
 * [Tobias Schmidt](http://github.com/grobie)
 * [Skylar Challand](http://github.com/sskylar)
-* [Alex Ehlke](http://github.com/aehlke)
+* [Alex Ehlke](http://github.com/aehlke) *current maintainer*
 
 
 ## License
 
-tag-it is released under the MIT license.
+tag-it is released under the [MIT license](http://github.com/aehlke/tag-it/raw/master/LICENSE).
 
diff --git a/TODO b/TODO
@@ -3,3 +3,12 @@ current one is deprecated, though still functional.
 
 * Add keyboard shortcuts for highlighting tags to remove them upon backspace.
 
+* minLength for autocomplete
+
+* hide the singleFieldNode
+
+* add quotesAllowed option (or quotedSpacesAllowed)
+
+* autogrow the input (http://stackoverflow.com/questions/931207/is-there-a-jquery-autogrow-plugin-for-text-fields)
+
+
diff --git a/css/examples.css b/css/examples.css
@@ -0,0 +1,36 @@
+@charset "UTF-8";
+
+
+#nav {
+    left:0;
+}
+#header {
+    padding-top:3em;
+}
+
+#header h1, #header h2 {
+    margin: 0 0 .2em 0;
+    padding-top: 1.5em;
+}
+hr + h3, hr + h4 {
+    margin-top: 0;
+}
+hr {
+    margin-bottom: .4em;
+}
+
+
+
+.myform {
+	padding:20px 0px;
+}
+.myform div.line {
+	clear:both;
+	min-height:50px;
+	margin-bottom:15px;
+}
+.myform label {
+	display:block;
+	font-weight:bold;
+	margin-bottom:5px;
+}