|
| 1 | +# Bootstrap Tags |
| 2 | + |
| 3 | +Bootstrap Tags is a jQuery plugin meant to extend Twitter Bootstrap to include tagging functionality. It supports Bootstrap 2.3.2 and ≥ 3.0. |
| 4 | + |
| 5 | +[](https://travis-ci.org/maxwells/bootstrap-tags) |
| 6 | + |
| 7 | +## Demo |
| 8 | +[http://maxwells.github.com/bootstrap-tags.html](http://maxwells.github.com/bootstrap-tags.html) |
| 9 | + |
| 10 | +## Installation |
| 11 | + |
| 12 | + $ bower install bootstrap-tags |
| 13 | + |
| 14 | +or |
| 15 | + |
| 16 | + $ git clone https://github.com/maxwells/bootstrap-tags.git |
| 17 | + --> js files are located in dist/js, CSS in dist/css |
| 18 | + |
| 19 | +## Features |
| 20 | +- Support for Bootstrap 2.3.2 and 3+ |
| 21 | +- Autosuggest (for typing or activated by pressing the down key when empty) |
| 22 | +- Bootstrap Popovers (for extended information on a tag) |
| 23 | +- Exclusions (denial of a specified list) |
| 24 | +- Filters (allowance of only a specified list) |
| 25 | +- Placeholder prompts |
| 26 | +- Uses bootstrap button-[type] class styling (customizing your bootstrap will change tag styles accordingly) |
| 27 | +- Extensible with custom functions (eg, before/after tag addition/deletion, key presses, exclusions) |
| 28 | + |
| 29 | +## Usage |
| 30 | + |
| 31 | + <!-- include bootstrap tags js, css files --> |
| 32 | + <script src='path/to/bootstrap-tags/dist/js/bootstrap-tags.min.js'></script> |
| 33 | + <link rel="stylesheet" type="text/css" href="path/to/bootstrap-tags/dist/css/bootstrap-tags.css" /> |
| 34 | + |
| 35 | + <div id="my-tag-list" class="tag-list"></div> |
| 36 | + <script> |
| 37 | + $(function() { |
| 38 | + // If using Bootstrap 2, be sure to include: |
| 39 | + // Tags.bootstrapVersion = "2"; |
| 40 | + $('#my-tag-list').tags({ |
| 41 | + tagData:["boilerplate", "tags"], |
| 42 | + suggestions:["basic", "suggestions"], |
| 43 | + excludeList:["not", "these", "words"] |
| 44 | + }); |
| 45 | + }); |
| 46 | + </script> |
| 47 | + |
| 48 | +## Documentation |
| 49 | + |
| 50 | +### Settings |
| 51 | + |
| 52 | +The following options are supported. Pass them as a javascript object to the `tags` jQuery function: |
| 53 | + |
| 54 | +```javascript |
| 55 | +$('selector').tags({ |
| 56 | + readOnly: true, |
| 57 | + tagData: ["a", "prepopulated", "list", "of", tags], |
| 58 | + beforeAddingTag: function(tag){ console.log(tag); } |
| 59 | +}); |
| 60 | +``` |
| 61 | + |
| 62 | +option | type | description | default |
| 63 | +-------|------|-------------|--------- |
| 64 | +`bootstrapVersion` | `String` | specify which version of bootstrap to format generated HTML for. Acceptable values are "2", "3" | `3` |
| 65 | +`tagData` | `Array` | a list of tags to initialize the tagging interace with | `[]` |
| 66 | +`tagSize` | `String` | describes what size input to use. Acceptable values are "lg", "md", or "sm" | `md` |
| 67 | +`readOnly` | `boolean` | whether or not to disable user input | `false` |
| 68 | +`suggestions` | `Array` | a list of terms that will populate the autosuggest feature when a user types in the first character. | `[]` |
| 69 | +`caseInsensitive` | `Boolean` | whether or not autosuggest should ignore case sensitivity | `false` |
| 70 | +`restrictTo` | `Array` | a list of allowed tags (will be combined with suggestions, if provided). User inputted tags that aren't included in this list will be ignored | `[]` |
| 71 | +`exclude` | `Array` | a list of case insensitive disallowed tags. Supports wildcarding (eg. `['*offensive*']` will ignore any word that has `offensive` in it) | `[]` |
| 72 | +`popoverData` | `Array` | a list of popover data. The index of each element should match the index of corresponding tag in `tagData` array | `null` |
| 73 | +`popovers` | `Boolean` | whether or not to enable bootstrap popovers on tag mouseover | whether `popoverData` was provided |
| 74 | +`popoverTrigger` | `String` | indicates how popovers should be triggered. Acceptable values are 'click', 'hover', 'hoverShowClickHide' | `hover` |
| 75 | +`tagClass` | `String` | which class the tag div will have for styling | `btn-info` |
| 76 | +`promptText` | `String` | placeholder string when there are no tags and nothing typed in | `Enter tags…` |
| 77 | +`maxNumTags` | `Integer` | Maximum number of allowable (user-added) tags. All tags that are initialized in the tagData property are retained. If set, then input is disabled when the number of tags exceeds this value. | `-1` (no limit) |
| 78 | +`readOnlyEmptyMessage` | `String` | text to be displayed if there are no tags in readonly mode. Can be HTML | `No tags to display...` |
| 79 | +`beforeAddingTag` | `function(String tag)` | anything external you'd like to do with the tag before adding it. Returning false will stop tag from being added | `null` |
| 80 | +`afterAddingTag` | `function(String tag)` | anything external you'd like to do with the tag after adding it | `null` |
| 81 | +`beforeDeletingTag` | `function(String tag)` | find out which tag is about to be deleted. Returning false will stop tag from being deleted | `null` |
| 82 | +`afterDeletingTag` | `function(String tag)` | find out which tag was removed by either pressing delete key or clicking the (x) | `null` |
| 83 | +`definePopover` | `function(String tag)` | must return the popover content for the tag that is being added. (eg "Content for [tag]") | `null` |
| 84 | +`excludes` | `function(String tag)` | return true if you want the tag to be excluded, false if allowed | `null` |
| 85 | + |
| 86 | +### Controlling tags |
| 87 | +Some functions are chainable (returns a `Tagger` object), and can be used to move the data around outside of the plugin. |
| 88 | + |
| 89 | +function | return type | description |
| 90 | +---------|-------------|------------- |
| 91 | +`hasTag(tag:string)` | `Boolean` | whether tag is in tag list |
| 92 | +`getTags()` | `Array` | a list of tags currently in the interface |
| 93 | +`getTagsWithContent()` | `Array` | a list of javascript objects with a `tag` property and `content` property |
| 94 | +`getTag(tag:string)` | `String` | returns tag as string |
| 95 | +`getTagWithContent(tag:string)` | `Object` | returns object with `tag` and `content` property (popover) |
| 96 | +`addTag(tag:string)` | `Tagger` | add a tag |
| 97 | +`renameTag(tag:string, newTag:string)` | `Tagger` | rename one tag to another value |
| 98 | +`removeLastTag()` | `Tagger` | removes last tag if it exists |
| 99 | +`removeTag(tag:string)` | `Tagger` | removes tag specified by string if it exists |
| 100 | +`addTagWithContent(tag:string, popoverContent:string)` | `Tagger` | Add a tag with associated popover content |
| 101 | +`setPopover(tag:string, popoverContent:string)` | `Tagger` | update a tag's associated popover content, if that tag exists |
| 102 | + |
| 103 | +Example: |
| 104 | + |
| 105 | +```javascript |
| 106 | +var tags = $('#one').tags( { |
| 107 | + suggestions : ["here", "are", "some", "suggestions"], |
| 108 | + popoverData : ["What a wonderful day", "to make some stuff", "up so that I", "can show it works"], |
| 109 | + tagData: ["tag a", "tag b", "tag c", "tag d"], |
| 110 | + excludeList : ["excuse", "my", "vulgarity"], |
| 111 | +} ); |
| 112 | +tags.addTag("tag e!!").removeTag("tag b").setPopover("tag c", "Changed popover content"); |
| 113 | +console.log(tags.getTags()); |
| 114 | +``` |
| 115 | + |
| 116 | +To reference a tags instance that you've already attached to a selector, (eg. $(selector).tags(options)) you can use $(selector).tags() or $(selector).tags(index) |
| 117 | + |
| 118 | +### Building |
| 119 | + |
| 120 | +For a one off: |
| 121 | + |
| 122 | + $ grunt build |
| 123 | + |
| 124 | +_To build continously_: |
| 125 | + |
| 126 | + $ grunt watch |
| 127 | + |
| 128 | +### Testing |
| 129 | + |
| 130 | + $ grunt test |
| 131 | + |
| 132 | +### Contributing |
| 133 | + |
| 134 | +If you spot a bug, experience browser incompatibility, or have feature requests, please submit them [here](https://github.com/maxwells/bootstrap-tags/issues). |
| 135 | + |
| 136 | +If you want to hack away to provide a new feature/bug-fix, please follow these guidelines: |
| 137 | + |
| 138 | +- Make changes to the coffeescript and sass files, not js/css. This is to ensure that the next person who comes in and edits upstream from js/css will not overwrite your changes. |
| 139 | +- Create a pull request for your feature branch, updating README documentation if necessary |
| 140 | + |
| 141 | +### License |
| 142 | + |
| 143 | +This project rocks and uses the MIT-LICENSE. |
| 144 | + |
| 145 | +### Author |
| 146 | + |
| 147 | +Max Lahey |
0 commit comments