Skip to content

Commit 5cfe4c3

Browse files
karahansl
kara
authored and
hansl
committed
docs(menu): add initial docs for menu (#906)
1 parent 5251c27 commit 5cfe4c3

File tree

2 files changed

+177
-5
lines changed

2 files changed

+177
-5
lines changed

‎src/components/menu/README.md

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# md-menu
2+
3+
`md-menu` is a list of options that displays when triggered. You can read more about menus in the
4+
[Material Design spec](https://material.google.com/components/menus.html).
5+
6+
## Usage
7+
8+
### Setup
9+
10+
`md-menu` relies on the existence of an app-wide `OverlayContainer`. This is the container in which
11+
it will display. You'll need to import this from `@angular2-material/core` and add it to your
12+
providers list on bootstrap.
13+
14+
*main.ts*
15+
```ts
16+
import { OverlayContainer } from '@angular2-material/core';
17+
18+
bootstrap(AppComponent, [
19+
OverlayContainer
20+
]);
21+
```
22+
23+
You'll also want to import the menu directives and add them to your component's directives array:
24+
25+
*my-comp.component.ts*
26+
```ts
27+
import {MD_MENU_DIRECTIVES} fom '@angular2-material/menu';
28+
29+
@Component({
30+
...
31+
directives: [MD_MENU_DIRECTIVES]
32+
})
33+
class MyComp {}
34+
```
35+
36+
### Simple menu
37+
38+
In your template, create an `md-menu` element. You can use either `<button>` or `<anchor>` tags for
39+
your menu items, as long as each is tagged with an `md-menu-item` attribute. Note that you can
40+
disable items by adding the `disabled` boolean attribute or binding to it.
41+
42+
*my-comp.html*
43+
```html
44+
<!-- this menu starts as hidden by default -->
45+
<md-menu>
46+
<button md-menu-item> Refresh </button>
47+
<button md-menu-item> Settings </button>
48+
<button md-menu-item> Help </button>
49+
<button md-menu-item disabled> Sign Out </button>
50+
</md-menu>
51+
```
52+
53+
Menus are hidden by default, so you'll want to connect up a menu trigger that can open your menu.
54+
You can do so by adding a button tag with an `md-menu-trigger-for` attribute and passing in the menu
55+
instance. You can create a local reference to your menu instance by adding `#menu="mdMenu"` to
56+
your menu element.
57+
58+
*my-comp.html*
59+
```html
60+
<!-- menu opens when trigger button is clicked -->
61+
<button md-icon-button [md-menu-trigger-for]="menu">
62+
<md-icon>more_vert</md-icon>
63+
</button>
64+
65+
<md-menu #menu="mdMenu">
66+
<button md-menu-item> Refresh </button>
67+
<button md-menu-item> Settings </button>
68+
<button md-menu-item> Help </button>
69+
<button md-menu-item disabled> Sign Out </button>
70+
</md-menu>
71+
```
72+
73+
Output:
74+
75+
<img src="https://material.angularjs.org/material2_assets/menu/default_closed.png">
76+
<img src="https://material.angularjs.org/material2_assets/menu/default_open.png">
77+
78+
### Toggling the menu programmatically
79+
80+
You can also use the menu's API to open or close the menu programmatically from your class. Please
81+
note that in this case, an `md-menu-trigger-for` attribute is still necessary to connect
82+
the menu to its trigger element in the DOM.
83+
84+
*my-comp.component.ts*
85+
```ts
86+
class MyComp {
87+
@ViewChild(MdMenuTrigger) trigger: MdMenuTrigger;
88+
89+
someMethod() {
90+
this.trigger.openMenu();
91+
}
92+
}
93+
```
94+
95+
*my-comp.html*
96+
```html
97+
<button md-icon-button [md-menu-trigger-for]="menu">
98+
<md-icon>more_vert</md-icon>
99+
</button>
100+
101+
<md-menu #menu="mdMenu">
102+
<button md-menu-item> Refresh </button>
103+
<button md-menu-item> Settings </button>
104+
<button md-menu-item> Help </button>
105+
<button md-menu-item disabled> Sign Out </button>
106+
</md-menu>
107+
```
108+
109+
### Customizing menu position
110+
111+
By default, the menu will display after and below its trigger. You can change this display position
112+
using the `x-position` (`before | after`) and `y-position` (`above | below`) attributes.
113+
114+
*my-comp.html*
115+
```html
116+
<md-menu x-position="before" #menu="mdMenu">
117+
<button md-menu-item> Refresh </button>
118+
<button md-menu-item> Settings </button>
119+
<button md-menu-item> Help </button>
120+
<button md-menu-item disabled> Sign Out </button>
121+
</md-menu>
122+
```
123+
124+
Output:
125+
126+
<img src="https://material.angularjs.org/material2_assets/menu/before_closed.png">
127+
<img src="https://material.angularjs.org/material2_assets/menu/before_open.png">
128+
129+
### Accessibility
130+
131+
The menu adds `role="menu"` to the main menu element and `role="menuitem"` to each menu item. It
132+
also adds `aria-hasPopup="true"` to the trigger element.
133+
134+
### Menu attributes
135+
136+
| Signature | Values | Description |
137+
| --- | --- | --- |
138+
| `x-position` | `before | after` | The horizontal position of the menu in relation to the trigger. Defaults to `after`. |
139+
| `y-position` | `above | below` | The vertical position of the menu in relation to the trigger. Defaults to `below`. |
140+
141+
### Trigger Programmatic API
142+
143+
**Properties**
144+
145+
| Name | Type | Description |
146+
| --- | --- | --- |
147+
| `menuOpen` | `Boolean` | Property that is true when the menu is open. It is not settable (use methods below). |
148+
| `onMenuOpen` | `Observable<void>` | Observable that emits when the menu opens. |
149+
| `onMenuClose` | `Observable<void>` | Observable that emits when the menu closes. |
150+
151+
**Methods**
152+
153+
| Method | Returns | Description |
154+
| --- | --- | --- |
155+
| `openMenu()` | `Promise<void>` | Opens the menu. Returns a promise that will resolve when the menu has opened. |
156+
| `closeMenu()` | `Promise<void>` | Closes the menu. Returns a promise that will resolve when the menu has closed. |
157+
| `toggleMenu()` | `Promise<void>` | Toggles the menu. Returns a promise that will resolve when the menu has completed opening or closing. |
158+
| `destroyMenu()` | `Promise<void>` | Destroys the menu overlay completely.
159+
160+
161+
### TODO
162+
163+
- Keyboard events: up arrow, down arrow, enter
164+
- `prevent-close` option, to turn off automatic menu close when clicking outside the menu
165+
- Custom offset support
166+
167+

‎src/components/menu/menu-trigger.ts

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ import {
4040
export class MdMenuTrigger implements AfterViewInit, OnDestroy {
4141
private _portal: TemplatePortal;
4242
private _overlayRef: OverlayRef;
43-
menuOpen: boolean = false;
43+
private _menuOpen: boolean = false;
4444

4545
@Input('md-menu-trigger-for') menu: MdMenu;
4646
@Output() onMenuOpen = new EventEmitter();
@@ -56,9 +56,11 @@ export class MdMenuTrigger implements AfterViewInit, OnDestroy {
5656

5757
ngOnDestroy() { this.destroyMenu(); }
5858

59+
get menuOpen(): boolean { return this._menuOpen; }
60+
5961
@HostListener('click')
6062
toggleMenu(): Promise<void> {
61-
return this.menuOpen ? this.closeMenu() : this.openMenu();
63+
return this._menuOpen ? this.closeMenu() : this.openMenu();
6264
}
6365

6466
openMenu(): Promise<void> {
@@ -75,14 +77,17 @@ export class MdMenuTrigger implements AfterViewInit, OnDestroy {
7577
}
7678

7779
destroyMenu(): void {
78-
if (this._overlayRef) { this._overlayRef.dispose(); }
80+
if (this._overlayRef) {
81+
this._overlayRef.dispose();
82+
this._overlayRef = null;
83+
}
7984
}
8085

8186
// set state rather than toggle to support triggers sharing a menu
8287
private _setIsMenuOpen(isOpen: boolean): void {
83-
this.menuOpen = isOpen;
88+
this._menuOpen = isOpen;
8489
this.menu._setClickCatcher(isOpen);
85-
this.menuOpen ? this.onMenuOpen.emit(null) : this.onMenuClose.emit(null);
90+
this._menuOpen ? this.onMenuOpen.emit(null) : this.onMenuClose.emit(null);
8691
}
8792

8893
/**

0 commit comments

Comments
 (0)