Merge pull request #55 from msarsha/new-api

closes #43 #36 #7 #4

Author: msarsha

.angular-cli.json

@@ -26,7 +26,8 @@
       "environments": {
         "dev": "environments/environment.ts",
         "prod": "environments/environment.prod.ts"
-      }
+      },
+      "showCircularDependencies": false
     }
   ],
   "e2e": {
@@ -55,6 +56,9 @@
   },
   "defaults": {
     "styleExt": "css",
-    "component": {}
+    "component": {},
+    "build": {
+      "showCircularDependencies": false
+    }
   }
 }

README.md

@@ -1,185 +1,105 @@
-### WIP !
-
-# ng2-right-click-menu
+## ng2-right-click-menu
 _Right click context menu for Angular 2+_
 
 __DEMO__ https://msarsha.github.io/ng2-right-click-menu/
 
-## How to use
+### Dependencies
 
-- `npm install --save ng2-right-click-menu`
-- import `ShContextMenuModule` into your app module
+`@angular/cdk`
 
-Add the `[sh-context]` directive to the desired element and bind an `IShContextMenuItem` array.
+`@angular/cdk/overlay-prebuilt.css"`
 
-Use the `[sh-data-context]` property to inject a context object of type `any`.
+### Setup
 
-````html
-<div class="box" [sh-context]="menuItems" [sh-data-context]="dataObject">
-  // content
-</div>
-````
+`npm install --save ng2-right-click-menu @angular/cdk`
 
-### `[sh-context]` (`IShContextMenuItem[]`)
+import `ShContextMenuModule`
 
 ````typescript
-  interface IShContextMenuItem {
-    label?: ((context: any) => string) | string; // as of version 0.0.11 this property is rendered as HTML
-    divider?: boolean;
-    onClick?($event: any): void;
-    visible?(context: any): boolean;
-    disabled?(context: any): boolean;
-    subMenu?: boolean;
-    subMenuItems?: IShContextMenuItem[];
-}
-````
-
-Example:
+import {ShContextMenuModule} from 'ng2-right-click-menu'
 
-````typescript
-  items: IShContextMenuItem[];
-  
-  this.items = [
-    {
-      label: '<span class="menu-icon">Save</span>',
-      onClick: this.clickEvent
-    },
-    {
-      label: (context) => `Edit ${context.someVariable}`,
-      onClick: this.clickEvent
-    },
-    {
-      label: '<b>Sub</b> Menu',
-      subMenu: true,
-      subMenuItems: [
-        {
-          label: 'Save',
-          onClick: this.clickEvent
-        },
-        {
-          label: 'Edit',
-          onClick: this.clickEvent
-        }]
-    }
-    {
-      divider: true
-    },
-    {
-      label: 'Remove',
-      disabled: ctx => {
-        return ctx.Two === 'Two';
-      },
-      onClick: this.clickEvent
-    },
-    {
-      label: (context) => `Hide ${context.name}`,
-      onClick: this.clickEvent,
-      visible: ctx => {
-        return ctx.One === 'One';
-      }
-    }
-  ];
-  
-  clickEvent($event: any){
-    console.log('clicked ', $event);
-  };
+@NgModule({
+  //...
+  imports: [ShContextMenuModule]
+  //...
+})
 ````
 
-### Passing a function to the label option
+import css file in your `styles.css`:
 
-You can pass either a string or a function that returns a string (using the data context as a parameter) to the `label` option of menu items. Passing a function allows the label to contain dynamic content.
-
-### onBeforeMenuOpen (v0.0.14)
-
-The `onBeforeMenuOpen` event can be used to cancel the menu from opening and allow to modify the menu items that will be display by the current event.
-
-The `open()` callback is used to continue the context menu event and can be injected with the new modified `IShContextMenuItem` items array. (optional. if items array is not provided the original array defined by `[sh-context]` will be used.)
-
-````html
-<div (onBeforeMenuOpen)="onBefore($event)" [sh-context]="items" [sh-data-context]="dataCtxOne">
-  Click Me !
-</div>
+````css
+  @import "~@angular/cdk/overlay-prebuilt.css";
 ````
 
-component:
+## Usage
 
-````typescript
-onBefore = (event: BeforeMenuEvent) => {
-    event.open([new items]);
-  };
-````
+#### Defining a Basic Menu Template
 
-`BeforeMenuEvent` interface:
-````typescript
-interface BeforeMenuEvent {
-  event: MouseEvent;
-  items: IShContextMenuItem[];
-  open(items?: IShContextMenuItem[]): void;
-}
-````
+The menu template is built using the `sh-context-menu` component as the menu wrapper,
+and nested `ng-template` with the `shContextMenuItem` directive for every menu item:
 
-### Options Object (v0.0.10)
+The `shContextMenuItem` directive provide a template variable (`let-data`) that gives you access to the data object attached to the menu.
 
 ````html
-<div [sh-options]="options"></div>
-````
-
-````typescript
-  options: IShContextOptions = {
-    // set options
-  }
+<sh-context-menu #menu>
+  <ng-template shContextMenuItem let-data (click)="onClick($event)">
+    <div>
+      Menu Item - {{data.label}}
+    </div>
+  </ng-template>
+</sh-context-menu>
 ````
 
-The options object is of type `IShContextOptions` and currently support the following options:
+#### Attaching Menu To An Element
 
-Options | Type | Default | Description
-:---:|:---:|:---:|:---|
-rtl|boolean|false|right to left support
-theme|string|light|menu color theme
+Attaching works by using the `shAttachMenu` directive and providing the `#menu` (from the above example) template variable:
 
-### Sub Menus (v0.0.9)
+The object provided to the `[shMenuData]` input will be available as a template variable inside `ng-template`s with `shContextMenuItem`
 
-Setting the `subMenu` property to `true` and the `subMenuItems` property to a `IShContextMenuItem[]` will render a sub menu.
+```html
+<div [shAttachMenu]="menu" [shMenuData]="data">Right Click Me</div>
+```
 
-````typescript
-{
-  label: 'Sub Menu',
-  subMenu: true,
-  subMenuItems: [
-    {
-      label: 'Save',
-      onClick: this.clickEvent
-    },
-    {
-      label: 'Edit',
-      onClick: this.clickEvent
-    }]
-}
-````
-
-#### The `onClick` handler
+## Sub Menus
 
-The `onClick` handler is a function that is being injected with `$event` parameter.
+Sub menu is attached to the `shContextMenuItem` directive using the `[subMenu]` input.
 
-The `$event` structure is:
+The `[subMenu]` input is provided with a `sh-context-menu`'s template variable (just like attaching a menu to an element).
 
-````typescript
-  {
-    menuItem: item,
-    dataContext: this.dataContext
-  }
+````html
+<sh-context-menu #menu>
+  <ng-template shContextMenuItem [subMenu]="#nestedMenu">
+    <div>
+      Menu Item - {{data.label}}
+    </div>
+  </ng-template>
+  <sh-context-menu #nestedMenu>
+    <ng-template shContextMenuItem let-data>
+      <div>
+        Menu Item - {{data.label}}
+      </div>
+    </ng-template>
+  </sh-context-menu>
+</sh-context-menu>
 ````
 
-Where the `menuItem` property is of type `IShContextMenuItem` and is the clicked menu item.
-
-And the `dataContext` is the object used on the `[sh-data-context]` binding.
+## API
 
+#### sh-context-menu
 
-#### The `disabled` and `visible` handlers
+Name | Type | Default | Description
+:---:|:---:|:---:|:---:
+[this]|any|null|the `this` context for input callbacks (visible) - typically the menu's host component
 
-Both get injected with the object used on the `[sh-data-context]` binding
+#### shContextMenuItem
 
-And should return a `boolean` to indicate if the current `IShContextMenuItem` is disabled or visible.
+Name | Type | Default | Description
+:---:|:---:|:---:|:---:
+[subMenu]|ShContextMenuComponent|null|sub menu
+[divider]|boolean|false|render a divider
+[closeOnClick]|boolean|true|should the menu close on click
+[visible]|(event: ShContextMenuClickEvent) => boolean|null|function to determine if a item is visible
+(click)|ShContextMenuClickEvent|null|click handler
 
 
 ### Setting up development env

changelog.md

@@ -1,3 +1,7 @@
+### 1.0.0 - BREAKING CHANGES
+
+new api using ng-template [#fc09e66](https://github.com/msarsha/ng2-right-click-menu/commit/fc09e6687ce7ca376708386b8841d5336b3ac82a)
+
 ### 0.0.16
 
 z-index increased to bring menu to foreground [#fc09e66](https://github.com/msarsha/ng2-right-click-menu/commit/fc09e6687ce7ca376708386b8841d5336b3ac82a)