|
| 1 | +# jQuery Tags Input Plugin |
| 2 | + |
| 3 | +Do you use tags to organize content on your site? |
| 4 | +This plugin will turn your boring tag list into a |
| 5 | +magical input that turns each tag into a style-able |
| 6 | +object with its own delete link. The plugin handles |
| 7 | +all the data - your form just sees a comma-delimited |
| 8 | +list of tags! |
| 9 | + |
| 10 | +[Get it from Github](https://github.com/xoxco/jQuery-Tags-Input) |
| 11 | + |
| 12 | +[View Demo](http://xoxco.com/projects/code/tagsinput/) |
| 13 | + |
| 14 | +[Test it yourself using this jsFiddle Demo](http://jsfiddle.net/7aDak/) |
| 15 | + |
| 16 | +Created by [XOXCO](http://xoxco.com) |
| 17 | + |
| 18 | + |
| 19 | +## Instructions |
| 20 | + |
| 21 | +First, add the Javascript and CSS files to your <head> tag: |
| 22 | + |
| 23 | + <script src="jquery.tagsinput.js"></script> |
| 24 | + <link rel="stylesheet" type="text/css" href="jquery.tagsinput.css" /> |
| 25 | + |
| 26 | +Create a real input in your form that will contain a comma-separated list of |
| 27 | +tags. You can put any default or existing tags in the value attribute, and |
| 28 | +they'll be handled properly. |
| 29 | + |
| 30 | + <input name="tags" id="tags" value="foo,bar,baz" /> |
| 31 | + |
| 32 | +Then, simply call the tagsInput function on any field that should be treated as |
| 33 | +a list of tags. |
| 34 | + |
| 35 | + $('#tags').tagsInput(); |
| 36 | + |
| 37 | +If you want to use jQuery.autocomplete, you can pass in a parameter with the |
| 38 | +autocomplete url. |
| 39 | + |
| 40 | + $('#tags').tagsInput({ |
| 41 | + autocomplete_url:'http://myserver.com/api/autocomplete' |
| 42 | + }); |
| 43 | + |
| 44 | +If you're using the bassistance jQuery.autocomplete, which takes extra |
| 45 | +parameters, you can also send in options to the autocomplete plugin, as |
| 46 | +described here. |
| 47 | + |
| 48 | + $('#tags').tagsInput({ |
| 49 | + autocomplete_url:'http://myserver.com/api/autocomplete', |
| 50 | + autocomplete:{selectFirst:true,width:'100px',autoFill:true} |
| 51 | + }); |
| 52 | + |
| 53 | +You can add and remove tags by calling the addTag() and removeTag() functions. |
| 54 | + |
| 55 | + $('#tags').addTag('foo'); |
| 56 | + $('#tags').removeTag('bar'); |
| 57 | + |
| 58 | +You can import a list of tags using the importTags() function... |
| 59 | + |
| 60 | + $('#tags').importTags('foo,bar,baz'); |
| 61 | + |
| 62 | +You can also use importTags() to reset the tag list... |
| 63 | + |
| 64 | + $('#tags').importTags(''); |
| 65 | + |
| 66 | +And you can check if a tag exists using tagExist()... |
| 67 | + |
| 68 | + if ($('#tags').tagExist('foo')) { ... } |
| 69 | + |
| 70 | +If additional functionality is required when a tag is added or removed, you may |
| 71 | +specify callback functions via the onAddTag and onRemoveTag parameters. Both |
| 72 | +functions should accept a single tag as the parameter. |
| 73 | + |
| 74 | +If you do not want to provide a way to add tags, or you would prefer to provide |
| 75 | +an alternate interface for adding tags to the box, you may pass an false into |
| 76 | +the optional 'interactive' parameter. The tags will still be rendered as per |
| 77 | +usual, and the addTag and removeTag functions will operate as expected. |
| 78 | + |
| 79 | +If you want a function to be called every time a tag is updated/deleted, set it |
| 80 | +as the 'onChange' option. |
| 81 | + |
| 82 | +By default, if the cursor is immediately after a tag, hitting backspace will |
| 83 | +delete that tag. If you want to override this, set the 'removeWithBackspace' |
| 84 | +option to false. |
| 85 | + |
| 86 | +## Options |
| 87 | + |
| 88 | + $(selector).tagsInput({ |
| 89 | + 'autocomplete_url': url_to_autocomplete_api, |
| 90 | + 'autocomplete': { option: value, option: value}, |
| 91 | + 'height':'100px', |
| 92 | + 'width':'300px', |
| 93 | + 'interactive':true, |
| 94 | + 'defaultText':'add a tag', |
| 95 | + 'onAddTag':callback_function, |
| 96 | + 'onRemoveTag':callback_function, |
| 97 | + 'onChange' : callback_function, |
| 98 | + 'removeWithBackspace' : true, |
| 99 | + 'minChars' : 0, |
| 100 | + 'maxChars' : 0 //if not provided there is no limit, |
| 101 | + 'placeholderColor' : '#666666' |
| 102 | + }); |
0 commit comments