maxwells / bootstrap-tags

Bootstrap-themed jquery tag interface

Bootstrap Tags

Bootstrap Tags is a jQuery plugin meant to extend Twitter Bootstrap to include tagging functionality. It supports Bootstrap 2.3.2 and ≥ 3.0.

Call for Maintainers

If you find this project useful and are interested in contributing or taking over, please add yourself to #70.

Demo

http://maxwells.github.com/bootstrap-tags.html

Installation

$ bower install bootstrap-tags

or

$ git clone https://github.com/maxwells/bootstrap-tags.git
--> js files are located in dist/js, CSS in dist/css

Features

• Support for Bootstrap 2.3.2 and 3+
• Autosuggest (for typing or activated by pressing the down key when empty)
• Bootstrap Popovers (for extended information on a tag)
• Exclusions (denial of a specified list)
• Filters (allowance of only a specified list)
• Placeholder prompts
• Uses bootstrap button-[type] class styling (customizing your bootstrap will change tag styles accordingly)
• Extensible with custom functions (eg, before/after tag addition/deletion, key presses, exclusions)

Usage

<!-- include bootstrap tags js, css files -->
<script src='path/to/bootstrap-tags/dist/js/bootstrap-tags.min.js'></script>
<link rel="stylesheet" type="text/css" href="path/to/bootstrap-tags/dist/css/bootstrap-tags.css" />

<div id="my-tag-list" class="tag-list"></div>
<script>
	$(function() {
		// If using Bootstrap 2, be sure to include:
		// Tags.bootstrapVersion = "2";
		$('#my-tag-list').tags({
			tagData:["boilerplate", "tags"],
			suggestions:["basic", "suggestions"],
			excludeList:["not", "these", "words"]
		});
	});
</script>

Documentation

Settings

The following options are supported. Pass them as a javascript object to the tags jQuery function:

$('selector').tags({
    readOnly: true,
    tagData: ["a", "prepopulated", "list", "of", tags],
    beforeAddingTag: function(tag){ console.log(tag); }
});

option	type	description	default
bootstrapVersion	String	specify which version of bootstrap to format generated HTML for. Acceptable values are "2", "3"	3
tagData	Array	a list of tags to initialize the tagging interface with	[]
tagSize	String	describes what size input to use. Acceptable values are "lg", "md", or "sm"	md
readOnly	Boolean	whether or not to disable user input	false
suggestions	Array	a list of terms that will populate the autosuggest feature when a user types in the first character	[]
suggestOnClick	Boolean	whether or not the autosuggest feature is triggered on click	false
caseInsensitive	Boolean	whether or not autosuggest should ignore case sensitivity	false
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	[]
exclude	Array	a list of case insensitive disallowed tags. Supports wildcarding (eg. ['*offensive*'] will ignore any word that has offensive in it)	[]
popoverData	Array	a list of popover data. The index of each element should match the index of corresponding tag in tagData array	null
popovers	Boolean	whether or not to enable bootstrap popovers on tag mouseover	whether popoverData was provided
popoverTrigger	String	indicates how popovers should be triggered. Acceptable values are 'click', 'hover', 'hoverShowClickHide'	hover
tagClass	String	which class the tag div will have for styling	btn-info
promptText	String	placeholder string when there are no tags and nothing typed in	Enter tags…
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)
readOnlyEmptyMessage	String	text to be displayed if there are no tags in readonly mode. Can be HTML	No tags to display...
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
afterAddingTag	function(String tag)	anything external you'd like to do with the tag after adding it	null
beforeDeletingTag	function(String tag)	find out which tag is about to be deleted. Returning false will stop tag from being deleted	null
afterDeletingTag	function(String tag)	find out which tag was removed by either pressing delete key or clicking the (x)	null
definePopover	function(String tag)	must return the popover content for the tag that is being added. (eg "Content for [tag]")	null
excludes	function(String tag)	return true if you want the tag to be excluded, false if allowed	null

Controlling tags

Some functions are chainable (returns a Tagger object), and can be used to move the data around outside of the plugin.

function	return type	description
hasTag(tag:string)	Boolean	whether tag is in tag list
getTags()	Array	a list of tags currently in the interface
getTagsWithContent()	Array	a list of javascript objects with a tag property and content property
getTag(tag:string)	String	returns tag as string
getTagWithContent(tag:string)	Object	returns object with tag and content property (popover)
addTag(tag:string)	Tagger	add a tag
renameTag(tag:string, newTag:string)	Tagger	rename one tag to another value
removeLastTag()	Tagger	removes last tag if it exists
removeTag(tag:string)	Tagger	removes tag specified by string if it exists
addTagWithContent(tag:string, popoverContent:string)	Tagger	Add a tag with associated popover content
setPopover(tag:string, popoverContent:string)	Tagger	update a tag's associated popover content, if that tag exists

Example:

var tags = $('#one').tags( {
	suggestions : ["here", "are", "some", "suggestions"],
	popoverData : ["What a wonderful day", "to make some stuff", "up so that I", "can show it works"],
	tagData: ["tag a", "tag b", "tag c", "tag d"],
	excludeList : ["excuse", "my", "vulgarity"],
} );
tags.addTag("tag e!!").removeTag("tag b").setPopover("tag c", "Changed popover content");
console.log(tags.getTags());

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)

Building

For a one off:

$ grunt build

To build continuously:

$ grunt watch

Testing

$ grunt test

Contributing

If you spot a bug, experience browser incompatibility, or have feature requests, please submit them here.

If you want to hack away to provide a new feature/bug-fix, please follow these guidelines:

• 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.
• Create a pull request for your feature branch, updating README documentation if necessary

License

MIT.

Author

Max Lahey

bootstrap-tags's Issues

Chainable "tagger object" documentation

Under "Controlling Tags", there is the phrase "Some functions are chainable (returns a Tagger object), and can be used to move the data around outside of the plugin"

It would be really nice to see some sort of example of this in the documentation / example files as I'm trying to join this rather nice tagging plugin to database functionality (i.e. an ajax call to a database)

Thanks!

Syntax error in "Implementation"

You have a syntax error in your example code:

$(function()) {
$('#my-tag-list').tags({
tagData:["boilerplate", "tags"],
suggestions:["basic", "suggestions"],
excludeList:["not", "these", "words"],
})
}

should be:

$(function() {
$('#my-tag-list').tags({
tagData:["boilerplate", "tags"],
suggestions:["basic", "suggestions"],
excludeList:["not", "these", "words"],
})
});

Passing Ids as well as getting Ids

Hi,

I was wondering if this library supports the ability to pass Ids to each tag as well as getting those passed Ids from the getTags function?

Estentially, what I want to do is pass the tags names and ids for the tags in the initialization. (e.g. $('#tags').tags({suggesstions: [ 'All', 'Accounting', 'Management' ], restrictTo: [ 'All', 'Accounting', 'Management' ], tagIds: [ '1', '2', '3' ] });)

And then would it be possible, using the getTags() function or another function (e.g. getTagIds()), to retrieve those ids as well as the tag names.

This would be very helpful if you could provide a solution for this to me. I would very much like to use this library, but I need it to support Ids.

Thanks!

~ Tyler

GitHub repo description misspelling

Your repo's description, below its name on its GitHub repo homepage, says
"Boostrap-themed [sic] jquery tag interface".
It should instead say
"Bootstrap-themed jquery tag interface"
(note the "t").

Something like "PromptText" but for ReadOnly Mode

It would be nice to have something like promptText for the ReadOnly mode. For example, if there are no tags I would like to provide some custom text like, "None yet" (for example).

This should be different from the PromptText, since the default messaging will be different if a user can add tags vs just being able to see them.

support for removeOnly besides readOnly

How can I have a list of tags which can only be removed?
I do not want the user to add any more tags, but only remove.

Popover content hides too quickly

Is there a way to keep the popover content from going away immediately after mousing-out of the tag? Ideally, the popover content would only go away if another area of the bootstrap-tags UI is clicked, or something outside of the bootstrap-ui is clicked.

For example, if I have a link in the popover, I am currently unable to click that link because the popover disappears as soon as I mouseout of the tag and move into the popover.

Is there a way to link tags?

Is it possible to wrap the tag in a anchor or pass it a url? I've been looking through the docs but I haven't gotten to the source yet. Would you open to pull requests with the ability?

How to change the placeholder of the tag-input?

The input box through which the tags are submitted contains the default placeholder as "Enter tags", it would be great if there could be way through which one can change this placeholder.
Many thanks for this plugin.

Set maximum number of allowed tags

It would be great if there would be a way through which I could set the maximum number of tags.

Padding issue

There is an issue with padding of the input field. If you try to change the padding via CSS, then the positioning of the input doesn't work properly and causes text to be underneath the tags.

como obtener valores ingresados en tags?

como puedo obtener los valores que ingresaron?

tagData: source from ajax or from custom function

I need to load my "tagData" source from a javascript function. How it is possible ?
I would like to avoid calling to much addTag function

Tx for your help

input-sm: tags too big.

https://github.com/maxwells/maxwells.github.io/blob/eb38ed6cbb055f82e699a365aabb613b9ed57e0f/bootstrap-tags.html
Chromium Version 54.0.2840.101 (64-bit) - Mac OS X 10.9.5

style the input field

Hey, this thing seems to work pretty well in the browsers I tested it on. I was wondering- how can increase the height of input text box? I supposed I will also have to increase the size of the tags. Is this possible?

Thank you,
Justin

How to maintain the listing of open suggestions?

How to maintain the listing of open suggestions and keep items that have been added in the suggestion list?

Necessary that the items added to continue appearing as it will add an icon "check" next to the tags that the user clicked.
Can someone help me please?

npm package

Could we have npm additional to bower?
Cheers,
Jonas

How to get suggestion list (full list) to show when tags-input receives focus?

Not sure if this is the right place for this question. Close this if it isn't. I have the plugin all set up and working. What I would like to have is either one of these things (prefferably number 1):

1. Rather than have a tag input, I would like a drop down list of all my available tags (I am restricting input). When they click one, it adds the tag.
2. Using the input rather than drop down list, when the input receives focus, show the whole list of suggestions.

How can I custom split char?

How can I custom split char? The default split char is ',' ,the question is how can I custom the split char such as . / | or use a whitespace as the split char?

ajax autocomplete option

Hi. Is it possible to use the plugin with autocomplete made with ajax? Can someone provide a sample code?
Regards.

getValues()

A function to return the array of the tags would be very useful.

Something like:

this.getValues = function() {

// get all tags values
     var values = [];

     $('#tags-labels').find('.tag.label > span').each(function(index) {
         values.push($(this).html());
     });

    return $values;
}

How can I make it not be case sensitive?

Is there an easy way to make this control not be case sensitive? I am trying to use it as a filter and I would rather the suggestion list pop up no matter what the case typed in is.

--nevermind, this was easy once I looked into the code

Could you please add return false in before adding/deleteing tag function

I was thinking for beforeAddingTag, beforeDeletingTag methods, if return false, we can avoid to add/delete tag. If return true, then can go ahead.

more events: beforeAddingTag, afterAddingTag, etc..

I'm trying to use your plugin for tags and it works well. In this very moment I'm facing this use case:

• I have a list of tags
• I add a tag
• I want to get the array of the values of all the tags after the insertion

I tried to use the callback whenAddingTag, but it's triggered before adding the new tag. So there's no way to get all the tags' values using whenAddingTag.
A hack like a timeout could be used, but I wouldn't like it.

So, what do you think about adding more events to be trigged, like:

beforeAddingTag()
afterAddingTag()
beforeDeletingTag()
afterDeletingTag()

for example, addTag() would become:

      this.addTag = function(tag) {
        var associatedContent;
        if ((_this.restrictTo === false || _this.restrictTo.indexOf(tag) !== -1) && _this.tagsArray.indexOf(tag) < 0 && tag.length > 0 && (_this.exclude === false || _this.exclude.indexOf(tag) === -1) && !_this.excludes(tag)) {
          _this.beforeAddingTag(tag);
          if (_this.displayPopovers) {
            associatedContent = _this.definePopover(tag);
            _this.popoverArray.push(associatedContent);
          }
          _this.tagsArray.push(tag);
          _this.afterAddingTag(tag);
          return _this.renderTags();
        }
      };

trigger event "tag removed"

it is necessary to trigger when user removes a tag by clicking on the

<a> <i class='icon-remove-sign icon-white'></i></a>

element, because pressedDelete only works when the backspace keyboard key is pressed

Add support for Bower

Add support for Bower and add version tags can really help using this great package.

How to show suggestions before typing

For example, if I have

suggestions: ['Apple', 'Adam', 'Ace']

I will no see any of these until I type a into the input. Is there any way to get these all to show on focus?

duplicated tags plus extra large input area

When trying out the demo for Bootstrap 2, as explained in the README Implementation section, tags are duplicated and outside a very large input area.

Check here:
http://jsfiddle.net/jogaco/WvzmN/

Making readonly responsive

I am trying to make a responsive switch between readonly and not readonly, from not readonly to readonly is fine, but after I want to edit again new tags are not added, nor old tags deleted, see:
http://stackoverflow.com/questions/28981014/making-bootstrap-tags-responsive-jquery-events-lost

Bootstrap-tags added to twitstrap resources

Hello,
We have just add Bootstrap-tags to twittstrap resources list
http://www.twittstrap.com/resources/details/bootstrap-tags
Under : Forms
Regards

CaseSensitive suggestions bug if tags start with an uppercase letter

Hi,

There is a bug with suggestions if tags in suggestions start with an uppercase letter /!
For instance, if suggestions are ["Alpha", "bravo"], typing :

With option caseInsensitive: false
"a" will suggest "Alpha" -> problem as caseInsensitive is false
"A" WON'T suggest "Alpha" -> that's the problem
"b" will suggest "bravo"
"B" won't suggest "bravo"

With option caseInsensitive: true
"a" won't suggest "Alpha"
"A" WON'T suggest "Alpha" -> that's the problem
"b" will suggest "bravo"
"B" will suggest "bravo"

Also, caseInsentive:true works only if tags in suggestions are in lowercase.

This is a real problem if you are using a smartphone which as keyboard set to enter an uppercase letter first, suggestions will never appear. Ex : iPhone 5.

Is this a know bug ?

Thanks,

Danjor.

mistaken repo

nevermind, wrong page, sorry

Funny behavior when inside of a container that is hidden on page load

When the main (initial) tag div is inside of a container that is hidden on page load, this library does not work very well. Behaves strangely. I had to write some code to wait to initialize bootstrap-tags until the div they were in was displayed.

Tag removal fails with special character (namely '&')

Reproduction Steps on demo page

1. add the following tag "abcdefgh &"
2. delete the tag above using the click to remove cross (NOT the backspace ability which appears to work)
3. delete one of the other tags and watch the previously deleted tag re-appear

Readme out of date. tags is not a function

https://github.com/maxwells/bootstrap-tags

.tags(

should be

.tagsinput(

How to submit tags ?

Hi,

I'm using bootstrap-tags with twitter bootstrap as a search bar and I'd like to know how to retreive tags and submit them?

For instance, if tags are "blue" and "green" :
A call should be done to "search" page like that :
website/search?tags=blue,green
or
website/search?tags1=blue&tag2=green

Thanks,

danjor.

Remove all tags/Reinitialize

How can we remove all tags from the input box?

when restricting to suggestions (not allowing new tags)

Line 17 we can read
this.restrictTo = (options.restrictTo != null ? options.restrictTo.concat(this.suggestions) : false);
Which will generate a JavaScript error
Uncaught TypeError: Object #<error> has no method 'concat'
if we give a value to restrictTo.
The following fixes it:
this.restrictTo = (options.restrictTo != null ? options.restrictTo = this.suggestions : false);

Hope this helps.

EDIT: actually it's NOT a bug if you specify restrictTo: [] instead of a boolean. Maybe a check on the value's type?

Popover does not auto close

Hi, nice typeahead library but why doesn't the popup close after opening?

promptText option ignored on initialization

I'm trying to have my own promptText on tagbox initialization, but it's not working. I can only get it to work after a tag is input, and then removed. Upon tag initialization, the default promptText of "Enter tags.." is used, and my option is ignored. This is what I'm using.

function initTags(name) {
var tagbox = $(name).tags({
tagData:[],
tagSize:'sm',
suggestions:[],
promptText:'Enter a word or phrase and press Return',
caseInsensitive: true
});
}
How can I fix this? I've tried clearing my cache, and session, and reloading everything from scratch. No such luck. Thanks.

Issue after clicking on a suggested tag

Hi and thanks for your speed,

Since v1.1.3, there is a bug, after clicking on a suggested tag, the suggestion dialog is still opened with nothing inside. Instead, the suggestion dialog should be hidden after selecting a tag.

While selecting a tag :

After clicking :

In addition, using either css of v1.0.2 or v1.0.3 does not change anything to the issue.

Thanks for considering this issue,

Danjor.

Readonly tags and position absolute

Hi

First of all. Great job! It's an amazing plugin. Works really well, but I had an issue with the readonly tags, because of the absolute position of the css. If I have content below the tags, it overlaps over them.
The solution is to change the position: absolute for the .tags class in the css.

Buuut, if you change the tags to readonly = false, the input field appears below the tags, which is not the desired behaviour. (changing to position: absolute for this works perfect).

Then, the solution, could be using position:relative for the readonly tags, and position:absolute for the non readonly.
I solved it when rendering the readonly div, adding to the .tags div another class called readonly, and giving it in the css the position: relative.

I don't know if it's the best solution, but it works for me.

Greetings!

How to change the placeholder of the taginput textbox?

The input box through which the tags are submitted contains the default placeholder as "Enter tags", it would be great if there could be way through which one can change this placeholder.
Many thanks for this plugin.

Any plan to continue the development of this brilliant stuff?

Hi Maxwells,

Just notice this excellent job on web. I would say I was stunned by your demo examples.

However, seems you've not updated this project for two months already. Will you continue its development, especially, considering the Twitter Bootstrap v3 has been announced.

Really looking forward to your news.

Regards,
Bryant

why not border-box

Out of interest, why on the .tags-input do you set box-sizing to content-box ? In my project I am using your plugin (thanks!) but changed it to border-box so that the input was responsive (but still supported internal left padding to simulate tag spacing for the cursor position). I'd have thought this would be more in keeping with bootstraps responsive approach.

demo page

Hello,
If you use https, the demo page is not working. It uses a secure protocol (https) and all the include files are in non-secure protocol (http). Modern browsers does not include unsecure files on secure main file.

Solution 1: use protocol-relative urls:
instead of

http://fonts.googleapis.com/css?family=PT+Serif:regular,italic,bold,bolditalic

use

//fonts.googleapis.com/css?family=PT+Serif:regular,italic,bold,bolditalic

Solution 2: use secure protocol
instead of

http://fonts.googleapis.com/css?family=PT+Serif:regular,italic,bold,bolditalic

use

https://fonts.googleapis.com/css?family=PT+Serif:regular,italic,bold,bolditalic

Regards

Does it support providing suggestions asynchronously?

Like after obtaining the suggestion data using an ajax request?

How to define a click function on the tag?

I have read the doc serverial times and do not find a way to do it.

Previous data gets lost on selection

 <div id="tax-list" class="tag-list"></div>

            $.getJSON('/api/tax/', function (result) {
                var arr = new Array();
                for (var k in result) {
                    arr.push(result[k].TaxCode);
                }
                $('#tax-list').tags({
                    tagData: [],
                    restrictTo: arr,
                    suggestions: arr
                });
            });

When I initialize the tags just like the code above, for the first time it initializes perfectly. When I select an item from the suggestions list, the page refreshes and I lose the previously selected data.

Wrong main values in bower.json

The grunt-bower-install uses the main value(s) from the bower.json file. Since the lib folder doesn't exist each build produces a error.

"main": [
    "lib/bootstrap-tags.js",
    "css/bootstrap-tags.css"
],

The following change fixes this problem.

"main": [
    "dist/js/bootstrap-tags.js",
    "dist/css/bootstrap-tags.css"
],

Thanks!