README

NGUX Context Menu

A simple right-click context menu for Angular 6 applications with support for Font Awesome icons via the @fortawesome/angular-fontawesome module.

Installation

This module has a dependency on @fortawesome/angular-fontawesome. Font Awesome provides several beautiful and modern icons for free that are available to use to decorate the context menu items. For now, this means that the dependency is required. The next release will remove this required dependency and instead offer it as an option. Until then, please install the required dependencies.

Install using Yarn

yarn add @fortawesome/fontawesome-svg-core
yarn add @fortawesome/free-solid-svg-icons
yarn add @fortawesome/angular-fontawesome
yarn add @ngux/contextmenu

Usage

The simplest way to use the context menu is first to import the ContextMenuModule in your component module:

import { ContextMenuModule } from '@ngux/contextmenu';

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

And then to include the context menu and triggers in your HTML file:

<!-- Context menu trigger -->
<p nguxContextMenuTrigger>Right Click Me!!</p>

<!-- Context Menu Definition -->
<ngux-contextmenu>
    <ngux-contextmenu-item [text]="'Say Hello World'" (click)="sayHello()"></ngux-contextmenu-item>
    <ngux-contextmenu-item [text]="'Say Goodbye'" (click)="sayGoodbye()"></ngux-contextmenu-item>
</ngux-contextmenu>

You can also use the nguxContextMenuTrigger directive on multiple HTML elements to open a single context menu definition from multiple triggers:

<!-- Context menu trigger -->
<p nguxContextMenuTrigger>Right Click Me!!</p>
<span nguxContextMenuTrigger>Right Click Me Too!!</span>
<button nguxContextMenuTrigger>Right Click Me Three!!</button>

<!-- Context Menu Definition -->
<ngux-contextmenu>
    <ngux-contextmenu-item [text]="'Say Hello World'" (click)="sayHello()"></ngux-contextmenu-item>
    <ngux-contextmenu-item [text]="'Say Goodbye'" (click)="sayGoodbye()"></ngux-contextmenu-item>
</ngux-contextmenu>

If you want to customize the action for the context menu depending on which trigger element you clicked on, you can simply register a (contextmenu) event listener on the trigger to set the selected element and then reference that element inside of the (click) event listeners.

<!-- Context menu trigger -->
<p nguxContextMenuTrigger (contextmenu)="selected = item1">Right Click Me!!</p>
<p nguxContextMenuTrigger (contextmenu)="selected = item2">Right Click Me!!</p>
<p nguxContextMenuTrigger (contextmenu)="selected = item3">Right Click Me!!</p>

<!-- Context Menu Definition -->
<ngux-contextmenu>
    <ngux-contextmenu-item [text]="'Introduce'" (click)="introduceSelected()"></ngux-contextmenu-item>
    <ngux-contextmenu-item [text]="'Dismiss'" (click)="dismissSelected()"></ngux-contextmenu-item>
</ngux-contextmenu>

There is plan for future support of a [model] property on the directive that will take care of this for you, but it is currently not implemented.

Scopes

The NGUX Context Menu simplifies defining context menus by using scopes to allow association between context menus and their triggers. When a trigger with a set [nguxScope] property is right-clicked, only the ngux-contextmenu element that has a matching scope will be opened. Two context menus cannot have the same scope.

In the following example, right-clicking on the content between the <p> tags will open the context menu, but right-clicking the content between the <span> tags will not.

<!-- Context menu trigger -->
<p nguxContextMenuTrigger [nguxScope]="'myscope'">Right Click Me!!</p>
<span nguxContextMenuTrigger>Right Click Me Too!!</span>

<!-- Context Menu Definition -->
<ngux-contextmenu [scope]="'myscope'">
    <ngux-contextmenu-item [text]="'Say Hello World'" (click)="sayHello()"></ngux-contextmenu-item>
    <ngux-contextmenu-item [text]="'Say Goodbye'" (click)="sayGoodbye()"></ngux-contextmenu-item>
</ngux-contextmenu>

Context Menu Items

The context menu will only include <ngux-contextmenu-item> tags in the final result of the menu. These components have three properties:

[text] - the text that will be displayed
[icon] - a valid @fortawesome/angular-fontawesome icon
[alias] - smaller text to display on the far right of the context menu item

A complete example demonstrating all the current features of the NGUX Context Menu is given below:

app.module.ts

import { ContextMenuModule } from '@ngux/contextmenu';
import { FontAwesomeModule } from '@fortawesome/angular-fontawesome';

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

app.component.ts

import { Component } from '@angular/core';
import { faGlobe } from '@fortawesome/free-solid-svg-icons';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  title = 'app';

  faGlobe = faGlobe;

  sayHello() {
    console.log("Hello World!");
  }

  sayGoodbye() {
    console.log("Goodbye!");
  }

  onButtonClick(): void {
    console.log("Button clicked!");
  }
}

app.component.html

<!-- Various triggers to test -->
<p nguxContextMenuTrigger [nguxScope]="'scopeName'">Right Click Me!!</p>
<p nguxContextMenuTrigger>Right Click Me!!</p>
<button nguxContextMenuTrigger 
    [nguxScope]="'scopeName'" 
    (click)="onButtonClick()">
    Right Click Me!!
</button>

<!-- Context Menu Definition -->
<ngux-contextmenu [scope]="'scopeName'">
    <ngux-contextmenu-item 
        [icon]="faGlobe" 
        [text]="'Say Hello World'" 
        [alias]="'Ctrl + s'" 
        (click)="sayHello()">
    </ngux-contextmenu-item>
    <ngux-contextmenu-item [text]="'Say Goodbye'" (click)="sayGoodbye()"></ngux-contextmenu-item>
</ngux-contextmenu>

Usage no npm install needed!