wlzch/jquery-mentions-input

Forked and updated from: https://github.com/podio/jquery-mentions-input.

Forked again from https://github.com/brennanmceachran/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);
   
   }
   });
   
   
   <p>
     Bam, you are in business.
   </p>
   
     

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, triggerChar, 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: 'mode' — always set to 'search' 'query' — what's been typed so far by the user 'triggerChar' — which is the character that started this data request, so you can take different actions on a '@' or '#'. 'callback' — function which needs to be called inside onDataRequest with a data collection to be searched on as a first argument. </td>
triggerChar	@	Trigger character which triggers the mentions search, when the character has been typed into the mentions input field. You can specify more than one trigger char by providing an array. eg triggerChar : ['@', '#'] Thanks to @ryanramage
onCaret	true	When set to true the autocomplete will be positioned beside the Caret (like how Github does it) Thanks to @juliocesar
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.
enableHighlight	boolean	Enables/disables the mention highlighting mechanism

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()		A method which 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()		A method which returns a collection of mentions as hash objects as a first parameter.

Events

Two events may be triggered on the initialized element Thanks to @johnfrederik

mention		Triggered when a new mention was added.
updated		Triggered when the input was updated.

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',
  'value' : 'Kenneth Auchenberg' // *new* the value to be displayed when displaying the mention
}

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) #[name](type:id)

Like:

  This is a message for @[Kenneth Auchenberg](contact:1) #[Issue 22](tag:22)

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

• Removed elastic-option since it wasn't really working without it. https://github.com/podio/jquery-mentions-input/issues/1)
• Fixed issue with space on search queries. ( https://github.com/podio/jquery-mentions-input/issues/24)

1.0.0

• Initial release.