Class: tagger

jQuery.widget.ui.tagger

new tagger(options)

tagger - Autocomplete and tagging widget
Parameters:
Name Type Description
options object Must pass in the available tags and optionally other information also
Version:
  • 0.7.1
Author:
  • Nick Palmer
Copyright:
  • Fivium ltd.
License:
  • http://github.com/fivium/jquery-tagger/blob/master/LICENSE
Source:

Members

(static) options

Default options, can be overridden by passing in an object to the constructor with these properties
Properties:
Name Type Description
availableTags Array Array of JSON tag objects
ajaxURL Array URL to autocomplete webservice for updating available tags
preselectedTags Array Array of tag ID's that are selected in the element (helps performance)
characterThreshold number How many characters must be typed before searching
characterLimit number How many characters can be entered into the input box
typingTimeThreshold number How many milliseconds to wait after the last keypress before filtering
caseSensitive boolean Case sensitive searching - defaults to false
placeholder string Placeholder text for input area
baseURL string Base URL used for images
imgDownArrow string URL for down arrow image (after baseURL)
imgRemove string URL for remove image (after baseURL)
imgSearch string URL for search image (after baseURL)
sortedOutput boolean Sort the suggestion lists by tag.sort
displayHierarchy boolean Indent suggestions to show hierarchy
indentMultiplier number When indenting suggestions, how much to multiple tag.level by
tabindexOffset number Then creating items it can tab to, what the tabindex should initially be
noSuggestText string Text to show when no suggestions can be found
emptyListText string Text to show when no suggestions in the list
searchTooltipText string Text to show as tooltip for the ajax search icon
ajaxErrorFunction string Function definition to use in the event of an AJAX request error, function(tagger, data)
loadingClass string Class on an sibling to the select used to fill while the js loads the tagger
inputExpandExtra number How many extra pixels to add on to the end of an input when expanding
fieldWidth string Override width e.g. 20em
fieldHeight string Override height e.g. 20em
suggestWidth string Set a hard width for the suggestion list (overrides maxwidth) e.g. 50em
suggestMaxWidth string Max width of the suggestion list (so it can be wider than the field) e.g. 50em
suggestMaxHeight string Max height of the suggestion list e.g. 20em
mandatorySelection boolean Make it mandatory that a value is chosen - defaults to false, no effect in multiselect mode
clearFilterOnBlur boolean Clear the filter text if any was left when the field loses focus (stops users thinking typed in text will be sent)
freeTextInput boolean Enable users to create options not defined in availableTags by hitting enter after typing text
freeTextPrefix string Optional string to prefix all free text option values with (helpful to differentiate server-side)
freeTextMessage string HTML string to show in the suggestions list containing the free text to hint that it can be added e.g. Add <em>%VALUE%</em> to list
freeTextSuggest string Allow free text values in the select to show up in the suggestions list
Source:

Methods

(protected, static) _addFreeText(freeTextValue)

Add a tag for given free text not specified in the available tags list
Parameters:
Name Type Description
freeTextValue string New text value to add an option for
Source:

(protected, static) _addTagFromID(tagID)

Add a tag, given a tags ID, to the widget and mark it as selected in the underlying select elements option list
Parameters:
Name Type Description
tagID string ID of the tag to add
Source:

(protected, static) _ajaxLoadSuggestions(value)

Load suggestions into suggestion list from ajaxURL
Parameters:
Name Type Description
value string the string value to filter by
Source:

(protected, static) _appendCharAndFilter(event)

Diverts the key press event passed to this function to whichever input is currently visible. Should be registered as an event handler for keypress events on elements that may be focused but are not the input being used; i.e. the drop-down arrow, suggestion items, tags, etc.
Parameters:
Name Type Description
event event the keypress event to handle
Source:

(static) _create()

Tagger widget constructor Based on the select element it is created on it reads information from it, Creates new elements for the tagger widget, adds event listeners and deals with pre-selected tags.
Source:

(protected, static) _filterSuggestions(value, hideSuggestions)

Filters the suggestions, using a provided value.
Parameters:
Name Type Description
value string the text string to filter by
hideSuggestions boolean boolean - should the suggestions be hidden if the value is less than the required character threshold?
Source:

(protected, static) _fireOnChangeAction()

If there is any onchange function defined on the original element, run it
Source:

(protected, static) _getVisibleInput()

Returns the tagger input or the tagger filter input depending on which is visible.
Source:
Returns:
jQuery wrapped InputElement

(static) _handleSuggestionItemInteraction(event)

Function to bind to suggestion list elements
Parameters:
Name Type Description
event
Source:

(protected, static) _inputExpand(input)

Set the width of an input box to fit the value string
Parameters:
Name Type Description
input InputElement HTML Input Element to set the width of
Source:

(protected, static) _isAlreadyDisplayingTag(tagID) → {boolean}

Check to see if a tag has already been selected
Parameters:
Name Type Description
tagID string ID of the tag to check for
Source:
Returns:
True if the tag is currently selected
Type
boolean

(protected, static) _loadSuggestions(suggestableTags, allowIndent)

Load tags into the suggestion list
Parameters:
Name Type Description
suggestableTags object Object containing members of tagID to tag object
allowIndent boolean Allow indenting of suggestion lists if true
Source:

(protected, static) _removeLastCharAndFilter(event)

Removes the last character
Parameters:
Name Type Description
event event the keypress event to handle
Source:

(protected, static) _removeTagByElem(tagElem, shouldHideMenu, shouldClearInputs)

Remove a tag, given a tags ID, to the widget and mark it as non-selected in the underlying select elements option list
Parameters:
Name Type Description
tagElem Object Div element of the tag clicked in the widget
shouldHideMenu boolean should the menu be hidden?
shouldClearInputs boolean should the input fields be cleared?
Source:

(protected, static) _selectionReset(shouldHideMenu, shouldClearInputs)

After selecting a tag from the suggestions, reset the tagger widget
Parameters:
Name Type Description
shouldHideMenu boolean should the menu be hidden?
shouldClearInputs boolean should the input fields be cleared?
Source:

(protected, static) _setSuggestionListDimensions()

Set the dimensions of the suggestion list container
Source:

(protected, static) _showMessageSuggestion(msg, className)

Show a message to the user in the suggestions list section instead of results
Parameters:
Name Type Description
msg string Message to show
className string Extra classes to add to the message item
Source:

(protected, static) _showSuggestions(focusFirstItem)

Show the suggestions list, making sure it's the correct size. Will initialise contents if necessary. Will focus first list item if requested to do so.
Parameters:
Name Type Description
focusFirstItem boolean whether the first item in the suggestion list received focus
Source:

(protected, static) _updateInputAndFilter(targetInput, newValue)

Updates the input or filter input and filters results. Also places focus in the input after updating the value.
Parameters:
Name Type Description
targetInput jQuery the jQuery wrapped input element to manipulate and focus
newValue string the new value to set
Source:

(static) filterTags(value)

Filter the available tags by the input text and load suggestions into suggestion list
Parameters:
Name Type Description
value string the string value to filter by
Source: