Tribute

ES6 Native @mentions

Autocomplete
zurb/tributezurb.github.io/tribute/example/tributejs

README

Tribute

CDNJS version Build Status

A cross-browser @mention engine written in ES6, no dependencies. Tested in Firefox, Chrome, iOS Safari, Safari, IE 9+, Edge 12+, Android 4+, and Windows Phone.

- Installing
- Initializing
- A Collection
- Events
- Tips
- Framework Support
- WYSIWYG Editor Support
- Example

Installing


There are a few ways to install Tribute; Bower, as an NPM Module, or by downloading from thedist folder in this repo.

NPM Module


You can install Tribute by running:

  1. ``` sh
  2. npm install tributejs
  3. ```

Or by adding Tribute to your package.json file.

Import into your ES6 code.

  1. ``` js
  2. import Tribute from "tributejs";
  3. ```

Ruby Gem


To use Tribute within a Rails project, you can add the following to the app's Gemfile:

    gem 'tribute'

Then, add the following to app/assets/javascripts/application.js:

  1. ``` js
  2. *= require tribute
  3. ```

And in app/assets/stylesheets/application.css:

  1. ```css
  2. //= require tribute
  3. ```

Webpack


To add Tribute to your webpack build process, start by adding it to your package.json and running npm install.

After installing, you need to update your Babel module loader to not exclude Tribute from being compiled by Webpack:

  1. ``` js
  2. {
  3.     test: /\.js$/,
  4.     loader: 'babel',
  5.     exclude: /node_modules\/(?!tributejs)/
  6. }
  7. ```

Download or Clone


Or you can download the repo or clone it localy with this command:

  1. ``` sh
  2. git clone git@github.com:zurb/tribute.git
  3. ```

You can then copy the files in the dist directory to your project.

  1. ``` html
  2. <link rel="stylesheet" href="js/tribute.css" />
  3. <script src="js/tribute.js"></script>
  4. ```

That's it! Now you are ready to initialize Tribute.

Initializing


There are two ways to initialize Tribute, by passing an array of "collections" or by passing one collection object.

  1. ``` js
  2. var tribute = new Tribute({
  3.   values: [
  4.     { key: "Phil Heartman", value: "pheartman" },
  5.     { key: "Gordon Ramsey", value: "gramsey" }
  6.   ]
  7. });
  8. ```

You can pass multiple collections on initialization by passing in an array of collection objects to collection.

  1. ``` js
  2. var tribute = new Tribute({
  3.   collection: []
  4. });
  5. ```

Attaching to elements


Once initialized, Tribute can be attached to an input, textarea, or an element that supports contenteditable.

  1. ``` html
  2. <div id="caaanDo">I'm Mr. Meeseeks, look at me!</div>
  3. <div class="mentionable">Some text here.</div>
  4. <div class="mentionable">Some more text over here.</div>
  5. <script>
  6.   tribute.attach(document.getElementById("caaanDo"));
  8.   // also works with NodeList
  9.   tribute.attach(document.querySelectorAll(".mentionable"));
  10. </script>
  11. ```

A Collection


Collections are configuration objects for Tribute, you can have multiple for each instance. This is useful for scenarios where you may want to match multiple trigger keys, such as @ for users and # for projects.

Collection object shown with defaults:

  1. ``` js
  2. {
  3.   // symbol or string that starts the lookup
  4.   trigger: '@',

  6.   // element to target for @mentions
  7.   iframe: null,

  9.   // class added in the flyout menu for active item
  10.   selectClass: 'highlight',

  12.   // class added to the menu container
  13.   containerClass: 'tribute-container',

  15.   // class added to each list item
  16.   itemClass: '',

  18.   // function called on select that returns the content to insert
  19.   selectTemplate: function (item) {
  20.     return '@' + item.original.value;
  21.   },

  23.   // template for displaying item in menu
  24.   menuItemTemplate: function (item) {
  25.     return item.string;
  26.   },

  28.   // template for when no match is found (optional),
  29.   // If no template is provided, menu is hidden.
  30.   noMatchTemplate: null,

  32.   // specify an alternative parent container for the menu
  33.   // container must be a positioned element for the menu to appear correctly ie. `position: relative;`
  34.   // default container is the body
  35.   menuContainer: document.body,

  37.   // column to search against in the object (accepts function or string)
  38.   lookup: 'key',

  40.   // column that contains the content to insert by default
  41.   fillAttr: 'value',

  43.   // REQUIRED: array of objects to match or a function that returns data (see 'Loading remote data' for an example)
  44.   values: [],

  46.   // When your values function is async, an optional loading template to show
  47.   loadingItemTemplate: null,

  49.   // specify whether a space is required before the trigger string
  50.   requireLeadingSpace: true,

  52.   // specify whether a space is allowed in the middle of mentions
  53.   allowSpaces: false,

  55.   // optionally specify a custom suffix for the replace text
  56.   // (defaults to empty space if undefined)
  57.   replaceTextSuffix: '\n',

  59.   // specify whether the menu should be positioned.  Set to false and use in conjuction with menuContainer to create an inline menu
  60.   // (defaults to true)
  61.   positionMenu: true,

  63.   // when the spacebar is hit, select the current match
  64.   spaceSelectsMatch: false,

  66.   // turn tribute into an autocomplete
  67.   autocompleteMode: false,

  69.   // Customize the elements used to wrap matched strings within the results list
  70.   // defaults to if undefined
  71.   searchOpts: {
  72.     pre: '<span>',
  73.     post: '</span>',
  74.     skip: false // true will skip local search, useful if doing server-side search
  75.   },

  77.   // Limits the number of items in the menu
  78.   menuItemLimit: 25,

  80.   // specify the minimum number of characters that must be typed before menu appears
  81.   menuShowMinLength: 0
  82. }
  83. ```

Dynamic lookup column


The lookup column can also be passed a function to construct a string to query against. This is useful if your payload has multiple attributes that you would like to query against but you can't modify the payload returned from the server to include a concatenated lookup column.

  1. ``` js
  2. {
  3.   lookup: function (person, mentionText) {
  4.     return person.name + person.email;
  5.   }
  6. }
  7. ```

Template Item


Both the selectTemplate and the menuItemTemplate have access to the item object. This is a meta object containing the matched object from your values collection, wrapped in a search result.

  1. ``` js
  2. {
  3.   index: 0;
  4.   original: {
  5.   } // your original object from values array
  6.   score: 5;
  7.   string: "<span>J</span><span>o</span>rdan Hum<span>p</span>hreys";
  8. }
  9. ```

Trigger tribute programmatically


Tribute can be manually triggered by calling an instances showMenuForCollection method. This is great for trigging tribute on an input by clicking an anchor or button element.

  1. ```
  2. <a id="activateInput">@mention</a>
  3. ```

Then you can bind a mousedown event to the anchor and call showMenuForCollection.

  1. ``` js
  2. activateLink.addEventListener("mousedown", function(e) {
  3.   e.preventDefault();
  4.   var input = document.getElementById("test");

  6.   tribute.showMenuForCollection(input);
  7. });
  8. ```

Note that showMenuForCollection has an optional second parameter called collectionIndex that defaults to 0. This allows you to specify which collection you want to trigger with the first index starting at 0.

For example, if you want to trigger the second collection you would use the following snippet: tribute.showMenuForCollection(input, 1);

Events


Replaced


You can bind to the tribute-replaced event to know when we have updated your targeted Tribute element.

If your element has an ID of myElement:

  1. ``` js
  2. document
  3.   .getElementById("myElement")
  4.   .addEventListener("tribute-replaced", function(e) {
  5.     console.log(
  6.       "Original event that triggered text replacement:",
  7.       e.detail.event
  8.     );
  9.     console.log("Matched item:", e.detail.item);
  10.   });
  11. ```

No Match


You can bind to the tribute-no-match event to know when no match is found in your collection.

If your element has an ID of myElement:

  1. ``` js
  2. document
  3.   .getElementById("myElement")
  4.   .addEventListener("tribute-no-match", function(e) {
  5.     console.log("No match found!");
  6.   });
  7. ```

Active State Detection


You can bind to the tribute-active-true or tribute-active-false events to detect when the menu is open or closed respectively.

  1. ``` js
  2. document
  3.   .getElementById("myElement")
  4.   .addEventListener("tribute-active-true", function(e) {
  5.     console.log("Menu opened!");
  6.   });
  7. ```

  1. ``` js
  2. document
  3.   .getElementById("myElement")
  4.   .addEventListener("tribute-active-false", function(e) {
  5.     console.log("Menu closed!");
  6.   });
  7. ```

Tips


Some useful approaches to common roadblocks when implementing @mentions.

Updating a collection with new data


You can update an instance of Tribute on the fly. If you have new data you want to insert into the current active collection you can access the collection values array directly:

  1. ``` js
  2. tribute.appendCurrent([
  3.   { name: "Howard Johnson", occupation: "Panda Wrangler", age: 27 },
  4.   { name: "Fluffy Croutons", occupation: "Crouton Fluffer", age: 32 }
  5. ]);
  6. ```

This would update the first configuration object in the collection array with new values. You can access and update any attribute on the collection in this way.

You can also append new values to an arbitrary collection by passing an index to append.

  1. ``` js
  2. tribute.append(2, [
  3.   { name: "Howard Johnson", occupation: "Panda Wrangler", age: 27 },
  4.   { name: "Fluffy Croutons", occupation: "Crouton Fluffer", age: 32 }
  5. ]);
  6. ```

This will append the new values to the third collection.

Programmatically detecting an active Tribute dropdown


If you need to know when Tribute is active you can access the isActive property of an instance.

  1. ``` js
  2. if (tribute.isActive) {
  3.   console.log("Somebody is being mentioned!");
  4. } else {
  5.   console.log("Who's this guy talking to?");
  6. }
  7. ```

Links inside contenteditable are not clickable.


If you want to embed a link in your selectTemplate then you need to make sure that the
anchor is wrapped in an element with contenteditable="false". This makes the anchor
clickable _and_ fixes issues with matches being modifiable.

  1. ``` js
  2. var tribute = new Tribute({
  3.   values: [
  4.     {
  5.       key: "Jordan Humphreys",
  6.       value: "Jordan Humphreys",
  7.       email: "getstarted@zurb.com"
  8.     },
  9.     {
  10.       key: "Sir Walter Riley",
  11.       value: "Sir Walter Riley",
  12.       email: "getstarted+riley@zurb.com"
  13.     }
  14.   ],
  15.   selectTemplate: function(item) {
  16.     return (
  17.       '+
  18.       item.original.email +
  19.       '">' +
  20.       item.original.value +
  21.       "</a></span>"
  22.     );
  23.   }
  24. });
  25. ```

How do I add an image to the items in the list?


You can override the default menuItemTemplate with your own output on initialization. This allows you to replace the innerHTML of the li of each item in the list. You can use item.string to return the markup for the fuzzy match.

  1. ``` js
  2. {
  3.   //..other config options
  4.   menuItemTemplate: function (item) {
  5.     return '<img src="'+item.original.avatar_url + '">' + item.string;
  6.   }
  7. }
  8. ```

Embedding Tribute in a scrollable container.


Sometimes you may need to have the Tribute menu attach to a scrollable parent element so that if the user scrolls the container the menu will scroll with it. To do this, you can set menuContainer to the node that is the scrollable parent.

  1. ``` js
  2. {
  3.   //..other config options
  4.   menuContainer: document.getElementById("wrapper");
  5. }
  6. ```

Loading remote data


If your data set is large or would like to pre filter your data you can load dynamically by setting the values to a function.

  1. ``` js
  2. {
  3.   //..other config options
  4.   // function retrieving an array of objects
  5.   values: function (text, cb) {
  6.     remoteSearch(text, users => cb(users));
  7.   },
  8.   lookup: 'name',
  9.   fillAttr: 'name'
  10. }
  11. ```

You would then define a function, in this case remoteSearch, that returns your data from the backend.

  1. ``` js
  2. function remoteSearch(text, cb) {
  3.   var URL = "YOUR DATA ENDPOINT";
  4.   xhr = new XMLHttpRequest();
  5.   xhr.onreadystatechange = function() {
  6.     if (xhr.readyState === 4) {
  7.       if (xhr.status === 200) {
  8.         var data = JSON.parse(xhr.responseText);
  9.         cb(data);
  10.       } else if (xhr.status === 403) {
  11.         cb([]);
  12.       }
  13.     }
  14.   };
  15.   xhr.open("GET", URL + "?q=" + text, true);
  16.   xhr.send();
  17. }
  18. ```

Hide menu when no match is returned


If you want the menu to not show when no match is found, you can set your noMatchTemplate config to the following:

  1. ``` js
  2. noMatchTemplate: function () {
  3.   return '<span style:"visibility: hidden;"></span>';
  4. }
  5. ```

Detaching Tribute instances


When you want to remove Tribute from an element you can call detach.

  1. ``` js
  2. tribute.detach(document.getElementById("caaanDo"));
  3. ```

This will remove all event listeners from the DOM that are associated with that element.

Trigger on multiple character strings


It is also possible to configure Tribute to trigger on a string consisting of multiple characters.

This example shows the usage of Tribute for autocompletion of variables:

  1. ``` js
  2. var tribute = new Tribute({
  3.   trigger: "{{",
  4.   values: [
  5.     { key: "red", value: "#FF0000" },
  6.     { key: "green", value: "#00FF00" }
  7.   ],
  8.   selectTemplate: function(item) {
  9.     return "{{" + item.original.key + "}}";
  10.   },
  11.   menuItemTemplate: function(item) {
  12.     return item.original.key + " = " + item.original.value;
  13.   }
  14. });
  15. ```

Framework Support


Vue.js — vue-tribute by@syropian

AngularJS 1.5+ — angular-tribute byZURB

Angular 2+ - ngx-tribute byLadder.io

Ruby — tribute-rb byZURB

Ember – ember-tribute byMalayaliRobz

WYSIWYG Editor Support


- Froala Editor - https://www.froala.com/wysiwyg-editor/examples/tribute-js

Brought to you by


ZURB, the creators of Helio

Design successful products by rapidly revealing key user behaviors. Helio makes it easy to get reactions on your designs quickly so your team can focus on solving the right problems, right now.