Home

About Tagtacular

Tagtacular is an open source jQuery plugin by Eric Burns for managing tags. Starting with version 0.8.5 it is released under the MIT License, the same license jQuery and jQueryUI use.

Earlier versions of Tagtacular were released under the Mozilla Public License 2.0, but in order to simplify things I've switched to MIT. Since Tagtacular requires jQuery and jQueryUI which are licensed under MIT, I wanted to remove the burden of understanding and complying with a second license from prospective users.

The goals of this project are that a tags management jQuery plugin should:

1. be very easy to setup with default behavior
2. have very flexible customization options
3. have minimal requirements and assumptions beyond jQuery and jQueryUI

This page is the complete documentation for this plugin, documenting every setting and interface function.

If you're just getting started, visit http://gototech.com/tagtacular for a demo and configuration examples. That is your best jumping on point for using this plugin.

This documentation is current for version 0.8.6.

Basic Concepts

1. The 'entity' is the thing are adding tags to and removing tags from. Each instance of tagtacular is working with one entity, either implied or specified by settings.entityId.
2. A tag is just a string, no metadata of any sort.
3. The entity tags list is the list of tags attached to the entity. This will be empty on initialization unless you provide a list in the settings object using settings.dataEntityList.
4. The system tags list is the list of tags that we know about, whether or not they are attached to the entity. This will also be empty on initialization unless you provide a list in the settings object using settings.dataSystemList.

Instantiate a Tagtacular Instance

1. Make sure you're including jQuery, jQueryUI, and tagtacular.js, in that order.
2. Create a
   element in the part of your DOM that you want the Tagtacular instance to appear. Give it some class or id you can search on later. Also slap a 'tagtacular_basic' class on your div if you want the default styles.
3. instantiate in javascript and store result, i.e "var tags1 = $('#mytagdiv').tagtacular({}); Include whatever options you would like to specify (see Configuring Tagtacular below for docs on all available options).
4. The tags1 variable can be used to get information or manipulate that tags instance, see Using Interface Functions section below.
5. It's okay to have multiple Tagtacular instances on the same page.
6. Take a look at the sample/index.html file in the distro for some useful examples.

Configuring Tagtacular

Tagtacular can be passed a configuration object on startup. Here are the options with their defaults:

Common Options

The options in bold are the ones that are probably the most important to knitting tagtacular into your web app.

Setting - Default	Description
commitAddTag - doNothing	The callback to be called when a tag is successfully added, in most cases this should be an ajax call to actually add the tag on the backend. This function will receive three parameters: tag name as a string, the entityId (or null if not set), and the settings object.
commitRemoveTag - doNothing	The callback to be called when a tag is successfully removed, in most cases this should be an ajax call to actually remove the tag on the backend. This function will receive three parameters: tag name as a string, the entityId (or null if not set), and the settings object.
configAddOnSwitch - true	If true on switching from edit to view mode we attempt to add a tag if there is text in the input.
configAddButtonText - 'Add'	The text to be displayed in the add button
configAllowedToEdit - true	If false, we enforce view mode and prevent switching to edit mode (and hide the switch to edit mode botton)
configAutocomplete - true	does the tag input have an autocomplete?
configAutocompletePrune - true	true signifies autocomplete should only show you system tags not yet on the entity, false means show all tags in autocomplete
configCaseInsensitive - true	are tags case insensitive for the purposes of checking for a dupe and sorting?
configDeleteSymbol - 'X'	html for the thing to click for deleting a tag in edit mode
configDeleteLastOnEmptyKeys - []	keycodes for keys that will remove the last tag when pressing it in an empty tag input field. empty by default (disabling this behavior). Setting this to [8] would emulate many popular tag systems by deleting on backspace. I'd recommend disabling sort if you enable this to avoid confusing behavior.
configDelimiters - [13 44]	key codes that will signify add tag, comma and enter keys by default
configEditTrayFirst - false	set to true to swap the order of the edit tray and tag tray
configFlashFailureHideAfter - 5	If set, hide a flash failure message after this many seconds. If false, never hide.
configFlashSuccessHideAfter - 5	If set, hide a flash success message after this many seconds. If false, never hide.
configFormatTagNamesOnInit - false	should the formatTagName callback be run on all entity and system tags on initialization? setting this to true will do nothing unless you also pass a formatTagName callback
configLimitToExisting - false	can only add tags already in our system to the entity
configMinimumTagLength - 1	minimum legal tag length
configMaximumTagLength - 32	maximum legal tag length
configPlaceholderText - false	string of placeholder text for the input field or false for none
configRenderFlashMessageSpan - true	Should we render the span for the default flash message solution? Only set to false if you've defined custom flashFailure and flashSuccess callbacks that don't depend on this element
configSelectBox - false	set to true to use a select box instead of an input or autocomplete
configShowAddButton - true	show the add button, which will attempt to add a tag on clicking
configShowSwitchButton - true	show switch mode button, which switches between edit and view modes
configSortTags - true	sort tags in tag tray on load and on each add
configSwitchButtonTextInEdit - 'Done'	text label for switch mode button in edit mode
configSwitchButtonTextInView - 'Edit'	text label for switch mode button in view mode
configTagSeperator - ''	separator text in betweeen tags
entityTags - []	initial tags on the current entity
entityId - null	the entity that this instance of tagtacular is manipulating tags for
entityType - null	the entity type that this instance of tagtacular is manipulating tags for, use when entityId is not enough to uniquely identify your entity
flashFailure - defaultFlashFailure	callback that will be called on failure message. gets passed the failure message string. Tagtacular displays this to the right of the edit tray by default.
flashSuccess - doNothing	callback that will be called on success message. gets passed the success message string. Tagtacular displays this to the right of the edit tray by default.
formatTagName - doNothing	takes a tag name string and returns a formatted tag name string on add (and also on initialization if configFormatTagNamesOnInit is true). you could use this to capitalize all the tags, for example.
messageAddTagSuccess - 'tag added'	message on successfully adding a tag (false to disable)
messageAddTagAlreadyExists - 'tag is already assigned'	message to display on a failed attempt to add a tag because it was already on the entity (false to disable)
messageEmptySelectBoxFailure - 'you must select a tag before adding it'	in an instance of Tagtacular configured to use a select box, message to display when attempting to add with if no tag is selected (false to disable)
messageRemoveTagSuccess - 'tag removed'	message to display on successful removal of a tag (false to disable)
messageTagNameInvalid - 'invalid tag name: tag names can only include letters, numbers, underscores, hyphens, and spaces' - This is the message to display on tag name validation fail not related to name length (usually illegal characters). The description should match what validationPattern actually enforces.
messageTagTooLong - 'tag name too long, maximum length of [configMaximumTagLength]'	message to display when a tag name fails validation because it is too long. [configMaximumTagLength] will be replaced with its value.
messageTagTooShort - 'tag name too short, minimum length of [configMinimumTagLength]'	message to display when a tag name fails validation because it is too short. [configMinimumTagLength] will be replaced with its value.
mode - 'edit'	which mode should we start in, view or edit?
remoteDataSource	jQueryUI Autocompleter compatible source callback to determine autocomplete suggestions. Not yet supported with both configLimitToExisting=true and configShowAddButton=true (but either/or is fine)
sort - caseInsensitiveSort	callback to sort tags. gets passed an array of strings to sort, should return sorted array.
systemTags - []	initial tags in the system, we'll add any entity tags to this list by default if they aren't already in this list
validationPattern - /^[0-9A-Za-z_- ]+$/	This is the regular expression to validate prospective tag name against, mainly a test for illegal characters. By default, letters, numbers, hyphens, and underscores are allowed.

Advanced Options

For non-standard implementation flexibility. Avoid using these if they aren't necessary, because it is easy to break important functionality. Take a look at the default function in tagtacular.js that you plan to replace for some helpful context - most of the classes you see are used by other parts of the plugin, but they can appear on any type of DOM element.

Setting	Default	Description
getAddButtonHtml	defaultGetAddButtonHtml	callback for returning html string for add button. gets passed settings object.
getLayoutHtml	defaultGetLayoutHtml	callback for returning html string for initial layout, gets passed the settings object
getSwitchButtonHtml	defaultGetSwitchButtonHtml	callback for returning html string for switch button. gets passed mode ('edit' or 'view' and settings object in that order
getTagHtml	defaultGetTagHtml	callback for returning html string for a tag. gets passed tag, mode ('edit' or 'view'), and settings object in that order
postDrawEditTray	doNothing	callback that gets called after the edit tray is rendered, gets passed mode ('edit' or 'view')
postDrawTagList	doNothing	callback that gets called after the tag list is rendered, gets passed mode ('edit' or 'view')
postSwitchLayout	doNothing	callback that gets called after the the mode is switched, gets passed new mode ('edit' or 'view')
validate	defaultValidate	callback to determine whether a tag passed to it has a legal name. true on success, false or error string on failure. gets passed the prospective tag name as a string, followed by the settings object. ValidationPattern should be used instead of this setting in most cases. Only use this for more advanced validation needs.

Using Interface Functions

After you initialize and display a tagtacular object with code like this: var myobj = $('#mytag").tagtacular();, the following interface functions are available on that tagtacular object.

Interface Function	Description
myobj.addTag(tagname)	Attempt to add tag with string tagname to the list of tags on the current entity
myobj.getEntityId()	Returns the entityId for this instance, or null if none has been set
myobj.getEntityType()	Returns the entityType for this instance, or null if none has been set
myobj.flashFailure(message)	flash a failure message
myobj.flashSuccess(message)	flash a success message
myobj.getEntityTags()	Returns an array of strings: the list of tags on the entity
myobj.getRemainingTags()	Returns an array of strings: the list of tags that are not currently assigned to the entity
myobj.getState()	Returns an up to date settings object representing this instance of tagtacular's state. mode, entityTags, and systemTags will reflect the current state.
myobj.getSystemTags	Returns an array of strings: the list of all the tags that we know about, whether ot not they are assigned to the entity.
myobj.removeTag(tagname)	removes the tag named tagname from the entity
myobj.tagtacular(settings)	initialize or reinitialize tagtacular object, not recommended to run after the first time

Styling

Two example styles are included in the css currently: tagtacular_textlike and tagtacular_basic. These are both pretty basic at the moment - good enough for a starting point. tagtacular_basic supports multiple colors. Just put the class on the container div before initializing.

<div id="tagtacular_1" class="tagtacular_basic yellow"></div>

<script type="text/javascript">
	var tags1 = $('#tagtacular_1').tagtacular({
             // config options go here
	});
</script>

I'm planning on doing some more work on the styles so people have some better out-of-the-box options. If CSS is your thing and you'd like to contribute to this project, let me know :-)

Examples

The Tagtacular Home Page has several examples with code. This will let you interact with some very different configurations of Tagtacular and see all of the configurations and code behind them. This is highly recommended for anyone new to Tagtacular. http://gototech.com/tagtacular