About

Tags plugin brings in the traditional tag functionality where user can assemble and edit list of tags. Tags plugin works especially well together with Autocomplete, Filter, Suggestions and Ajax plugins to provide full spectrum of features. It can also work on its own and just do one thing – tags.

Examples

Options

Tags plugin options are grouped under tags when passed to the $().textext() function. For example:

$('textarea').textext({
    plugins: 'tags',
    tags: {
        items: [ "tag1", "tag2" ]
    }
})

tags.enabled (true)

This is a toggle switch to enable or disable the Tags plugin. The value is checked each time at the top level which allows you to toggle this setting on the fly.

tags.items (null)

Allows to specify tags which will be added to the input by default upon initialization. Each item in the array must be of the type that current ItemManager can understand. Default type is String.

html.tag ('<div class="text-tags"/>')

HTML source that is used to generate a single tag.

html.tags ('<div class="text-tag"><div class="text-button"><span class="text-label"/><a class="text-remove"/></div></div>')

HTML source that is used to generate container for the tags.

Events

Tags plugin dispatches or reacts to the following events.

isTagAllowed

Tags plugin triggers the isTagAllowed event before adding each tag to the tag list. Other plugins have an opportunity to interrupt this by setting result of the second argument to false. For example:

$('textarea').textext({...}).bind('isTagAllowed', function(e, data)
{
    if(data.tag === 'foo')
        data.result = false;
})

The second argument data has the following format: { tag : {Object}, result : {Boolean} }. tag property is in the format that the current ItemManager can understand.

tagClick1.3.0

Tags plugin triggers the tagClick event when user clicks on one of the tags. This allows to process the click and potentially change the value of the tag (for example in case of user feedback).

$('textarea').textext({...}).bind('tagClick', function(e, tag, value, callback)
{
    var newValue = window.prompt('New value', value);

    if(newValue)
        callback(newValue, true);
})

Callback argument has the following signature:

function(newValue, refocus)
{
    ...
}

Please check out example.

Methods

TextExtTags.addTags(tags)

  • tags {Array} List of tags that current ItemManager can understand. Default is String.

Adds specified tags to the tag list. Triggers isTagAllowed event for each tag to insure that it could be added. Calls TextExt.getFormData() to refresh the data.

TextExtTags.containerElement()

Returns HTML element in which all tag HTML elements are residing.

TextExtTags.getTagElement(tag)

  • tag {Object} Tag object in the format that current ItemManager can understand. Default is String.

Returns HTML element for the specified tag.

TextExtTags.init(core)

  • core {TextExt} Instance of the TextExt core class.

Initialization method called by the core during plugin instantiation.

TextExtTags.initPriority()

Returns initialization priority of the Tags plugin which is expected to be less than the Autocomplete plugin because of the dependencies. The value is 100.

TextExtTags.isTagAllowed(tag)

  • tag {Object} Tag object that the current ItemManager can understand. Default is String.

Wrapper around the isTagAllowed event which triggers it and returns true if result property of the second argument remains true.

TextExtTags.onBackspaceKeyDown(e)

  • e {Object} jQuery event.

Reacts to the backspaceKeyDown event. When backspace key is pressed in an empty text field, deletes last tag from the list.

TextExtTags.onClick(e)

  • e {Object} jQuery event.

Reacts to the mouse click event.

TextExtTags.onContainerMouseMove(e)

  • e {Object} jQuery event.

Reacts to user moving mouse over the tags. Whenever the cursor moves out of the tags and back into where the text input is happening visually, the tags container is sent back under the text area which allows user to interact with the text using mouse cursor as expected.

TextExtTags.onEnterKeyPress(e)

  • e {Object} jQuery event.

Reacts to the enterKeyPress event and adds whatever is currently in the text input as a new tag. Triggers isTagAllowed to check if the tag could be added first.

TextExtTags.onGetFormData(e, data, keyCode)

  • e {Object} jQuery event.

  • data {Object} Data object to be populated.

  • keyCode {Number} Key code that triggered the original update request.

Reacts to the getFormData event triggered by the core. Returns data with the weight of 200 to be greater than the Autocomplete plugin data weight. The weights system is covered in greater detail in the getFormData event documentation.

TextExtTags.onInputMouseMove(e)

  • e {Object} jQuery event.

Reacts to user moving mouse over the text area when cursor is over the text and not over the tags. Whenever mouse cursor is over the area covered by tags, the tags container is flipped to be on top of the text area which makes all tags functional with the mouse.

TextExtTags.onPostInit(e)

  • e {Object} jQuery event.

Reacts to the postInit event triggered by the core and sets default tags if any were specified.

TextExtTags.onPreInvalidate(e)

  • e {Object} jQuery event.

Reacts to the preInvalidate event and updates the input box to look like the tags are positioned inside it.

TextExtTags.removeTag(tag)

  • tag {Object} Tag object in the format that current ItemManager can understand. Default is String.

Removes specified tag from the list. Calls TextExt.getFormData() to refresh the data.

TextExtTags.renderTag(tag)

  • tag {Object} Tag object in the format that current ItemManager can understand. Default is String.

Creates and returns new HTML element from the source code specified in the html.tag option.

TextExtTags.tagElements()

Returns all tag HTML elements.

TextExtTags.toggleZIndex(e)

  • e {Object} jQuery event.

Toggles tag container to be on top of the text area or under based on where the mouse cursor is located. When cursor is above the text input and out of any of the tags, the tags container is sent under the text area. If cursor is over any of the tags, the tag container is brought to be over the text area.

TextExtTags.updateFormCache()

Creates a cache object with all the tags currently added which will be returned in the onGetFormData handler.

Fork me on GitHub