jquery.mentionsInput

jquery.mentionsInput is a small, but awesome UI component that allows you to "@mention" someone in a text message, just like you are used to on Facebook or Twitter.

This project is written by Kenneth Auchenberg, and started as an internal project at Podio, but has then been open sourced to give it a life in the community.

Examples

Basic example (source)

Get marked-up value Get mentions collection

AJAX example. (Getting data by AJAX, and filter in callback - source)

Download and source

You can grab the latest source from the repository on GitHub by clicking here: https://github.com/podio/jquery-mentions-input.

Getting started

  1. Add a script reference to jquery.mentionsInput.js:
    <script src='jquery.mentionsInput.js' type='text/javascript'></script>
  2. Add a bit of markup: 
    <textarea class='mention'>

  3. Initialise the mentionsInput: 

    $('textarea.mention').mentionsInput({
  onDataRequest:function (mode, query, callback) {
    var data = [
      { id:1, name:'Kenneth Auchenberg', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' },
      { id:2, name:'Jon Froda', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' },
      { id:3, name:'Anders Pollas', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' },
      { id:4, name:'Kasper Hulthin', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' },
      { id:5, name:'Andreas Haugstrup', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' },
      { id:6, name:'Pete Lacey', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' }
    ];

    data = _.filter(data, function(item) { return item.name.toLowerCase().indexOf(query.toLowerCase()) > -1 });

    callback.call(this, data);
  }
});

    Bam, you are in business.

Configuration

jquery.mentionsInput does have a number of extra configuration options which you may change to customise the way it behaves.

The meaning of the options and their default values are listed below.

onDataRequest function(mode, query, callback) This function is a callback function which is used to provide data for the autocomplete. When a search starts this function is called with following arguments: 'search', the query (what's been typed), and a callback function which needs to be called inside onDataRequest with a data collection to be searched on as a first argument.
triggerChar @ Trigger character which triggers the mentions search, when the character has been typed into the mentions input field.
minChars 2 The minimum amount of characters after the trigger character necessary to perform a search.
showAvatars true | false Toggles whether or not items within the autocomplete-dropdown will be rendered with an icon/avatar.
classes object Object which contains classes used in the layout as key/value pairs.
templates object Object which contains templates used to render the layout as key/value pairs.

Methods

jquery.mentionsInput does expose a number of public methods, you can call on an instance.

init Initialises the mentionsInput component on a specific element.
reset Resets the component, clears all mentions.
val(callback) An async method which accepts a callback function and returns a value of the input field (including markup) as a first parameter of this function.

This is the value you want to send to your server.
getMentions(callback) An async method which accepts a callback function and returns a collection of mentions as hash objects as a first parameter.

Query data structure

When the component is preforming a "query" on the data specified through the onDataRequest-callback, it's expecting a specific data structure to be returned. 

{
  'id'    : 1,
  'name'  : 'Kenneth Auchenberg',
  'avatar': 'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif',
  'icon'  : 'icon-16 icon-person',
  'type'  : 'contact'
}

"avatar" property is a URL used for image avatars when "showAvatars"-option is enabled

"icon" property is a className used for avatars when "showAvatars"-option is disabled

"type" property specifies an object type which is used in the marked-up version of the mentions result

Markup format

When mentions are being added to the input, a marked-up version of the value is generated, to allow the mentions to be extracted, parsed and stored later. 

  This is a message for @[name](type:id)

Like:

  This is a message for @[Kenneth Auchenberg](contact:1)

Browser support

jquery.mentionsInput has been tested in Firefox 6+, Chrome 15+, and Internet Explorer 8+.

Please let us know if you see anything weird. And no, we will no make it work for older browsers. Period.

Dependencies

jquery.mentionsInput is written as a jQuery extension, so it naturally requires jQuery (1.6+). In addition to jQuery, it also depends on underscore.js (1.2+), which is used to simplify stuff a bit.

The component is also using the new HTML5 "input" event. This means older browsers like IE8 need a polyfill which emulates the event (it is bundled).

The component itself is implemented as a small independent function, so it can easily be ported to frameworks other than jQuery.

Furthermore all utility functions have been centralized in the utils-object, which can be replaced with references if you already got functions like htmlEncode, etc.

To make the component grow and shrink to fit it’s content, you can include jquery.elastic.js

License

MIT License - http://www.opensource.org/licenses/mit-license.php

Change Log

1.0.1

1.0.0