Tag Manager

Introduction

This is an extensible javascript tag manager. jQuery is required.

Support is specifically built in for Bootstrap typeahead.

Javscript is written in TypeScript. Style sheets are written in LESS for easy customization.

Examples

Default

Bulk Tag Handling Methods

These methods are used to initially populate the tag manager and reset it.

Validate Handler

Type 'invalid' to trigger an invalid tag.

Validate Handler for Duplicates

Duplicates are not allowed and the existing value is hilighted.

Validate and Remove Handlers for Max Tags

view source

$('#example7').tagmanager({
    validateHandler: function(tagManager, tag, isImport) {
        if (isImport) return tag;

        var maxTags = 3;
        var tagCount = tagManager.tagIds.length;

        if (tagCount == maxTags - 1) {
            tagManager.$element.attr('placeholder', 'Maximum of ' +
                maxTags + ' tags');
        }

        if (tagCount == maxTags) {
            return false;
        }

        return tag;
    },

    removeHandler: function(tagManager, tag, isEmpty) {
        tagManager.$element.attr('placeholder', 'Add Tags');

        return true;
    }
});

Create Element Handler

Bootstrap Typeahead

There is an issue with Bootstrap: Typeahead requires a selected value. So if you use typeahead the user must select an existing tag.

Code

HTML

<input type="text" name="tags1" placeholder="Add Tags"
    id="tagmanager" autocomplete="off">

Javascript

$('#tagmanager').tagmanager();

Configuration

$('#tagmanager').tagmanager({
    strategy: 'array',
    tagFieldName: 'tags[]',
    ajaxCreate: 'http://localhost/tag/create',
    ajaxRemove: 'http://localhost/tag/remove',
    initialCap: true,
    backspaceChars: [ 8 ],
    delimiterChars: [ 13, 44, 188 ],
    createHandler: function(tagManager, tag, isImport) {
        return;
    },
    removeHandler: function(tagManager, tag, isEmpty) {
        return true;
    },
    createElementHandler: function(tagManager, tagElement, isImport) {
        tagManager.$element.before(tagElement);
    },
    validateHandler: function(tagManager, tag, isImport) {
        return tag;
    }
});

Strategy

$('#tagmanager').data('tagmanager').options.optionName;
Option Name	Datatype	Default	Description
strategy	string	array	The array strategy is default and creates a new input field for each tag created with the tag manager. The field name is defined with option tagFieldName and must be an array such as "tags[]". The second strategy is ajax which requires ajaxCreate and ajaxRemove options with URLs to post a tag to when created or removed. The third strategy is none which requires the programmer to use handlers to persist tags.
tagFieldName	string	tags[]	When using the array strategy this option is required. This is the input field name for each tag to be sent back to your server as part of a form submission.
ajaxCreate	string	null	A URL to post an ajax request to when a tag is created. e.g. http://localhost/tag/create?id=5 The createHandler can be used for more fine-grained ajax handling.
ajaxRemove	string	null	A URL to post an ajax request to when a tag is removed/deleted. e.g. http://localhost/tag/remove?id=5 The removeHandler can be used for more fine-grained ajax handling.

Options

$('#tagmanager').data('tagmanager').options.optionName;
Option Name	Datatype	Default	Description
initialCap	boolean	true	Proper case the first word of each tag?
backspaceChars	array	[ 8 ]	An array of character key codes to accept as "backspace" when the field is empty. When the input field is empty and a backspace character is entered the last tag will be removed. Pass an empty array the config to disable this feature.
delimiterChars	array	[ 13, 44, 188 ]	An array of character key codes to delimit a tag. If char code 13, Enter Key, is in the list the default form submission mechanism is overridden to allow the enter key to act as a delimiter.

Handlers

$('#tagmanager').data('tagmanager').options.handlerName;
Handler Name	Parameters	Description
createHandler	tagManager, tag, isImport	Fired when a new tag is created with the tag manager. Fired before createElementHandler. No return value. isImport will be true if fired from the populate method.
removeHandler	tagManager, tag, isEmpty	Fired when a tag is removed from the tag manager. If the return value is true the tag will be removed. isEmpty will be true if fired from the empty method.
createElementHandler	tagManager, jQuery element, isImport	When a tag is created in the manager this function will pass the genereated jQuery element as a parameter so it can be processed and placed anywhere on the page. isImport will be true if fired from the populate method.
validateHandler	tagManager, tag, isImport	If the validator handler returns false the tag will not be created. If the validator handler returns any other value that value will be created instead of the original value. isImport will be true if fired from the populate method.

Firing Order


Method Name	Handler	Can Cancel
create	validateHandler	yes
create	createHandler	no
create	createElementHandler	no
remove	removeHandler	yes

Methods

$('#tagmanager').data('tagmanager').methodName(parameter1, parameter2);
Method Name	Parameters	Description
create	tag, isImport	Adds a tag to the tag manager. The first parameter is the tag string. The second parameter defaults to false and will not fire ajaxCreate if true.
remove	tagElement, isEmpty	Removes a tag from the tag manager. The first parameter is the jQuery handle of the tag span created from the tag manager. The second parameter defaults to false and will not fire ajaxRemove if true.
populate	tags	Import an array of tags without firing ajaxCreate.
empty	none	Clears all tags from the tag manager without firing ajaxRemove.
pop	none	Pop the last tag. Used when backspace is fired.

Data

$('#tagmanager').data('tagmanager').fieldName;
Field Name	Description
options	An object with the complete tag manager configuration.
tagIds	An array of span ids of all tags in the tag manager.
tagStrings	An array of tag strings of all tags in the tag manager. This array is paired with tagIds. A paired array approach is a simpler implementation than a hash.