Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Clone this wiki locally
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:
- be very easy to setup with default behavior
- have very flexible customization options
- 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.
- 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.
- A tag is just a string, no metadata of any sort.
- 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.
- 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
- Make sure you're including jQuery, jQueryUI, and tagtacular.js, in that order.
- 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.
- The tags1 variable can be used to get information or manipulate that tags instance, see Using Interface Functions section below.
- It's okay to have multiple Tagtacular instances on the same page.
- Take a look at the sample/index.html file in the distro for some useful examples.
Tagtacular can be passed a configuration object on startup. Here are the options with their defaults:
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  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.
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.
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
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.
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 :-)
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