Home

Eric W. Burns edited this page Jun 1, 2017 · 77 revisions
Clone this wiki locally

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.
  7. 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