shubhamuniyal / ngx-tribute

Angular 2+ directive for Zurb Tribute

ngx-tribute

This is an Angular 2+ wrapper directive for native JS library for @mentions - tributejs. It supports contenteditable and Reactive Forms.

To install:

npm i tributejs ngx-tribute

Note: At least version 3.3.5 of tributejs is required.

Usage

Import NgxTributeModule:

import {NgxTributeModule} from 'ngx-tribute';

@NgModule({
  imports: [
    NgxTributeModule
  ],
  ...
})
export class AppModule { }

and use [ngxTribute] directive on your input, textarea or [contenteditable]:

<input [ngxTribute]="tributeOptions">

Import default CSS from node_modules/tributejs/dist/tribute.css to get a minimal working example.

Check tributejs docs for a detailed description of the configuration object.

Check a demo and it's code to see different ways of using the directive. It integrates well with template forms and reactive forms.

API Docs

Inputs:

• [ngxTribute] - Tribute.js configuration object, refer to original library docs for details
• [implicitFormControl] - pass FormControl if it's value will be altered by Tribute (this isn't required if you use [formControl] or [formControlName] directives)
• [menuContainer] - if you want to use menuContainer option from Tribute.js, pass element obtained by template ref variable here, instead of manually retrieving element from DOM. See "Using menuContainer" below for an explanation and example

Outputs:

• (onMentioned) - emits the whole value of input each time when a new mention is added
• (mentionItemSelected) - emits the original object of input each time when a new mention is added

Reactive forms

When using Angular reactive forms, form control value needs to be updated whenever you select any mention. This directive does it automatically by intercepting Angular [formControl] or [formControlName] directive attached to the same element as Tribute.js or one of its ancestors. If for some reason you're not using standard directives, you can use [implicitFormControl] input to pass form control, which should be updated, directly to ngxTribute directive.

See demo app and it's code for an example.

Using menuContainer

Tribute.js allows to pass a DOM element, to which menu should be attached, by using menuContainer option. It's a bad practice in Angular to obtain elements via document methods (eg. document.getElementById()). Angular gives it's own methods for accessing DOM nodes. In this case, Template Reference Variable should be used.

See following example:

@Component({
    template: `
        <input [ngxTribute]="options" [menuContainer]="container">
        <div #container></div>
    `
})
class MyComponent {
    options = {
        values: [
            { key: 'foo', value: 'Foo' },
            { key: 'bar', value: 'Bar' },
            { key: 'baz', value: 'Baz' }
        ],
        positionMenu: false
    }
}

Contributing

• library code is located in projects/ngx-tribute and demo code in src
• run npm install after cloning the repo
• run npm run build-lib to build the library used by demo app
• run npm start to start a dev server with demo app
• whenever you change something in the library code, you need to run npm run build-lib to see that changes in demo app
• after finishing, run npm run build-demo to rebuild a demo app

Story behind this lib

We were rewriting a project from AngularJS 1.5 to Angular 2 and faced the lack of a good library for @mentions in the new Angular. There were some, but we needed a good support for [contenteditable], and none of existing solutions satisfied our needs. We decided to check for some lib written in pure JS and add an Angular wrapper for it. We were so happy with the result, that we decided to share that with the rest of the world :)

This is just a tribute