Vitologi inputtags plugin


Description

This plugin transforms ordinary form input fields into fields which allow easy creation of tags.

Simple usage


unique tags (example)

var input = document.getElementById("input"),
    inputInputtags = new Inputtags(input);
Simple use case to work with unique tags

Repeat tags


not unique tags (example)

var input = document.getElementById("input"),
    inputInputtags = new Inputtags(input,{
        "duplicate":true
    });
Repeat tags case allows you work with not unique tags

Tag objects


tag-objects (example)

var input = document.getElementById("input"),
    inputInputtags = new Inputtags(input,{
        "keyName":"key",
        "valueName":"value"
    });
Work with array of objects without messing object's stucture if set "keyName" and "valueName" properties.

Tag sources


tag sources (example)

var input = document.getElementById("input"),
    inputInputtags = new Inputtags(input,{
        "source":function(cursorValue){
            var source;

            if(cursorValue.toLowerCase().indexOf("t") !== -1){
                source = ["Tag1","Tag2","Tag3","Tag4","Tag5","Tag6"];
            }else{
                source = ["Link1","Link2","Link3","Link4","Link5","Link6"];
            }

            return source;
        }
});
Inputtags is also capable to use different sources of pre-defined tags.

Style customization


changed css class (example)

var input = document.getElementById("input"),
    inputInputtags = new Inputtags(input,{
        "source":function(cursorValue){
            return ["Tag1","Tag2","Tag3","Link1","Link2","Link3"];
        },
        "getTagClass":function(tag){
            var text = tag.getVal();
            return (text.indexOf("Link")!== -1)?"bInputtags__tag label-info":"bInputtags__tag";
        }
    });
In this case we check item and set custom style for it.
Inputtags can be styled by modifying "getClass" handlers of parameters. For example:

  • "getInputtagsClass" set css class for Inputtags element
  • "getTagClass" set css class for Tag element
  • "getSourceItemClass" set css class for Item element in source list

Block's structure

Let's observe some basic aspect of plugin structure like used classes and HTML elements.
raw input element (HTML element)
Inputtags
Tag x
Tag x
Cursor
SourceList
source list item
source list item
source list item
     There is only four object which construct Inputtags (Cursor, SourceList, Tag and Inputtags). Each of them has own view (HTML element) and some individual methods. You have direct access only to the base object (Inputtags), but all constructors are put in vitologi.inputtags._class namespace. This allows you overwrite some prototype methods or create object instance.
     Also there is an object with parameters (imagine a builder). You can redefine it when you create Inputtags from HTML-input.

Parameters and classes API

Below you can find API description of main plugin components.
Class/Method name Description
Inputtags(element, parameters) Main plugin's constructor, it is responsible for combination of all plugin elements and synchronization with modified input
element - raw form input (HTML element)
parameters - configuration object
getVal() get all tags data
setVal(item) set tags data
item - array or JSON-string of tags
hasVal(item) check the existence of the tag/item
item - tag data
clear() remove all tags from inputtags
synchronize() synchronize object with DOM Element
Tag(item, parameters) Tags constructor
item - tag data
parameters - configuration object
getView() get block's HTML element
getVal() get tag data
Cursor(parameters) Entry point for input tags
parameters - configuration object
getView() get block's HTML element
getVal() get cursor value
setVal(val) set cursor value
val - setted text
SourceList(parameters) List of tags (source)
parameters - configuration object
getView() get block's HTML element
addItem(item) append new item to tags list
item - item (tag data)
removeAllItems() delete all items from tags list
Property name Description
_inputtags store current Inputtags object
_cursor store current Cursor object
_sourceList store current SourceList object
_tags[] array of Tag objects
duplicate {boolean} flag which allows to have duplicate tags
keyName {string} name of object's identifier (if it is set, than tag's data is treated like an object)
valueName {string} name of object's property to show (if it is set, than tag's data is treated like an object)
getInputtagsClass(item) returns string with css class name to set style for Inputtags HTML element
item - Inputtags instance
getCursorClass(item) returns string with css class name to set style for Cursor HTML element
item - Cursor instance
getTagClass(item) returns string with css class name to set style for Tag HTML element
item - Tag instance
getTagRemoverClass(item) return string with css class name to set style for Tag component (close button)
item - Tag instance
getSourceListClass(item) returns string with css class name to set style for SourceList HTML element
item - SourceList instance
getSourceItemClass(item) returns string with css class name to set style for SourceList component (list item)
item - tag data object
source(item) returns array of tag's data, which is used to create the source list
item - user input text (value of Cursor)
onChange() execute after add or remove tags
cursorHandler(e) handler for cursor's "keyup" event
e - event object
sourceListHandler(item, e) handler for choosing item in source list
item - chosen list item (tag data) e - event object
addTag(tag) function appends tag to collection and HTML element to view
tag - added tag
removeTag(tag) function removes tag from collection and HTML element to view
tag - removed tag
* be aware, environments (this) of all executable function can be changed

Extend plugin (asynchronous resource creation)


changed css class (example)

var input = document.getElementById("input"),

    // small function for server simulation
    serverSimulator = function(needle, callback){

        window.setTimeout(function(){
            callback(null, ["Tag1","Tag2","Tag3","Link1","Link2","Link3"]);
        }, (Math.random()*2)*1000);

    },

    inputInputtags = new Inputtags(input,{

        "source":function(cursorValue){

            // get current list and cursor
            var list = this._sourceList,
                cursor = this._cursor;

            // send request on server
            serverSimulator(cursorValue, function(error, result){
                if(error)throw new Error("Get server data error.");

                // clear exist data
                list.removeAllItems();

                var aItem = result,
                    cursorIsEmpty = cursor.getVal() === "",
                    itemRegexp = new RegExp("^"+cursor.getVal()),
                    len = aItem.length,
                    i = 0, item;

                if(!len)return;

                // add received data to the list
                for(; i<len; i++){
                    item = aItem[i];
                    if(cursorIsEmpty || !itemRegexp.test(item))continue;
                    list.addItem(result[i]);
                }
            });
        }
    });
Just start typing like "Li" or "T" (uppercase is need) and source list will be filled by some items (2s delay).
This is an example of extend plugin. In fact, ajax source feature will be added in next version (I hope :)).
In the case above, you see how easily we can get access to main plugin components and overwrite them.