Fork me on GitHub

# Taggle.js

Form-ready, Delicious style tagging made easy.

Github

##### Example 1 - Creating a basic Taggle

This example is as simple as it gets. Duplicate tags are prevented by default. You can also delete tags by pressing backspace or hovering and clicking with your mouse.

###### HTML:

###### JavaScript:

    new Taggle('example1');

##### Example 2 - Prefilled tags

It's easy to prepopulate the text field as well. Just pass an array of tags as displayed below.

###### HTML:

###### JavaScript:

    new Taggle('example2', {
        tags: ['These', 'are', 'prefilled', 'tags']
    });

##### Example 3 - Duplicate tag alert

This example takes advantage of how much CSS control Taggle.js allows you to have. Specify your own duplicate CSS class by using the `duplicateTagClass` option. Try entering one of the already existing tags to see a subtle alert notifying you of the tag.

> Note: the bounce animation happens as a result of the css class being added. Not javascript. Therefore you will not see the animation in IE9 and below.

###### HTML:

###### JavaScript:

    new Taggle('example3', {
        tags: ['Try', 'entering', 'one', 'of', 'these', 'tags'],
        duplicateTagClass: 'bounce'
    });

#### Example 4 - Autocomplete

Taggle.js just provides the basic functionality to add tags to a field but it also provides a basic API so you can wrap it for additional functionality with other libraries such as jQueryUI Autocomplete. Same HTML. Just a little bit more javascript code.

###### HTML:

###### JavaScript:

    var example4 = new Taggle('example4');
    var container = example4.getContainer();
    var input = example4.getInput();

    $(input).autocomplete({
        source: faux,
        appendTo: container,
        position: { at: "left bottom", of: container },
        select: function(event, data) {
            event.preventDefault();
            //Add the tag if user clicks
            if (event.which === 1) {
                example4.add(data.item.value);
            }
        }
    });

#### Example 5 - onBeforeTagAdd/onTagAdd & onBeforeTagRemove/onTagRemove

Want to hook into before a tag is added or removed? Okay. Want to call a callback function after a tag has been added or removed? Fine.

> I'm using innerHTML for simplicity however you should look into innerText or textContent depending on what browser you're supporting.

###### HTML:

###### JavaScript:

    var text = document.getElementById('example5-event');

    // Make sure to return true or false in onBeforeTagAdd and onBeforeTagRemove
    new Taggle('example5', {
        onBeforeTagAdd: function(event, tag) {
            return confirm('You really wanna add ' + tag + '?');
        },
        onTagAdd: function(event, tag) {
            text.innerHTML = 'You just added ' + tag;
        },
        onBeforeTagRemove: function(event, tag) {
            return confirm('You really wanna remove ' + tag + '?');
        },
        onTagRemove: function(event, tag) {
            text.innerHTML = 'You just removed ' + tag;
        }
    });

#### Example 6 - add / remove

You can programatically add and remove tags as well.

###### HTML:

###### JavaScript:

    var taggle = new Taggle('example6');

    taggle.add('one');
    taggle.add(['two', 'three', 'four', 'four', 'five', 'five']);
    taggle.remove('five');
    taggle.remove('four', true);

#### Example 7a - Allowed tags

Sometimes you'll want to restrict the users to adding only certain tags.

###### HTML:

###### JavaScript:

    var taggle = new Taggle('example7a', {
        placeholder: 'Type your favorite type of juice... (hint: orange)',
        allowDuplicates: true,
        allowedTags: ['orange']
    });

#### Example 7b - Disallowed tags

Conversely, you'll want to restrict the users from adding certain tags.

###### HTML:

###### JavaScript:

    var taggle = new Taggle('example7b', {
        placeholder: 'Type your favorite type of juice... (hint: apple)',
        allowDuplicates: true,
        disallowedTags: ['apple']
    });

#### Misc - Tags around the web

Tag fields can be really useful because it makes it easy for your users to provide the type of data values you need without having to worry about if they submitted values with trailing spaces, extra commas, etc.

As you can see below, it's easy to style Taggle.js with just a little bit of css.

###### Delicious

###### Stack Overflow

#### Options

additionalTagClasses: `[String='']`

By default a class of `taggle` will be assigned to each tag. If you need more, add them in one string separated by spaces.

allowDuplicates: `[Boolean=false]`

Set to true if you want to allow duplicate tags to be entered in the taggle field.

preserveCase: `[Boolean=false]`

Set to true if you want to allow tags to retain case as entered in the taggle field (lowercased by default).

saveOnBlur: `[Boolean=false]`

Allow the saving of a tag on blur, rather than it being removed by default.

clearOnBlur: `[Boolean=true]`

Clear the input element on blur if there is a text value.

duplicateTagClass: `[String='']`

The class name that will be set onto duplicate tag.

containerFocusClass: `[String='active']`

This will be the class added to the taggle field div when focused.

focusInputOnContainerClick: `[Boolean=true]`

If `true` then `input` will be focused when `container` receives a click event.

hiddenInputName: `[String='taggles[]']`

Since a hidden input is appended for each tag added, you might need a name for them when submitting to the server.

placeholder: `[String='Enter tags...']`

A placeholder.

submitKeys: `[188, 9, 13]`

Keycodes that will add a tag. Comma, Tab, and Enter are the recommended and default keyCodes.

tabIndex: `[Number=1]`

If your taggle field is within a form, it might be useful to specify a tabIndex so that a user can still tab through form fields like normal.

tags: `[Array=[]]`

These will be the tags that should be preloaded in the taggle field when the plugin loads.

delimeter: `[',']`

The default delimeter character to split tags on.

attachTagId: `[Boolean=false]`

Add an ID to each of the tags that will be available in onTagAdd, onBeforeTagRemove, & onTagRemove.

allowedTags: `[Array=[]]`

Tags that the user will be restricted to.

inputFormatter(inputElement)

Function hook called with the to-be-added input DOM element.

tagFormatter(element)

Hook fired before the tag li element is appended to the DOM. This gives the author a chance to edit the list item before it is added. Must return an li element.

onBeforeTagAdd(event, tag)

Hook fired before a tag is added. Provides the event and tag text. Return false to prevent the tag from being added.

onBeforeTagRemove(event, tag [, callback])

Hook fired before a tag is removed. Provides the event and tag text. Return a falsy value to prevent the tag from being removed. The callback argument can be called to remove the tag.

onTagAdd(event, tag)

Callback fired whenever a tag is added. Provides the event and tag text.

onTagRemove(event, tag)

Callback fired whenever a tag is removed. Provides the event and tag text.

#### Methods

setOptions(options)

Set options at runtime. This should be an object with the taggle options as keys

add(tag(s))

Pass an array of strings or just one string to programatically add tags.

remove(tag, remove_all=false)

Pass a string to remove the most recent occurance of the tag. Pass true to the second argument to remove all occurances of the tag.

removeAll()

Remove all tags at once, including duplicates.

getTags() `Returns {Object}`

Get an object with an array of the tag text and an array of tag list elements.

getTagElements() `Returns {Array}`

Get an object with an array of the tag list elements.

getTagValues() `Returns {Array}`

Get an array of the tag text.

getInput() `Returns {Element}`

Get the actual text input.

getContainer() `Returns {Element}`

Get the original textarea container.