Skip to content

Commit 538f2d9

Browse files
mmalerbammalerba
committed
add examples
1 parent 0a590a8 commit 538f2d9

30 files changed

+454
-296
lines changed

‎src/lib/sidenav/README.md

Lines changed: 1 addition & 170 deletions
Original file line numberDiff line numberDiff line change
@@ -1,170 +1 @@
1-
**NOTE: The <code>mat-sidenav-layout</code> element is deprecated. <code>mat-sidenav-container</code>
2-
should be used instead.**
3-
4-
5-
# MatSidenav
6-
7-
MatSidenav is the side navigation component for Angular Material. It is composed of two components: `<mat-sidenav-container>` and `<mat-sidenav>`.
8-
9-
## Screenshots
10-
11-
<img src="https://material.angularjs.org/material2_assets/sidenav-example.png">
12-
13-
14-
## `<mat-sidenav-container>`
15-
16-
The parent component. Contains the code necessary to coordinate one or two sidenav and the backdrop.
17-
18-
## `<mat-sidenav>`
19-
20-
The sidenav panel.
21-
22-
### Bound Properties
23-
24-
| Name | Type | Description |
25-
| --- | --- | --- |
26-
| `position` | `"start"\|"end"` | The position of this sidenav. In LTR direction, `"start"` will be shown on the left, `"end"` on the right. In RTL, it is reversed. `"start"` is used by default. If there is more than 1 sidenav on either side the container will be considered invalid and none of the sidenavs will be visible or toggleable until the container is valid again. |
27-
| `mode` | `"over"\|"push"\|"side"` | The mode or styling of the sidenav, default being `"over"`. With `"over"` the sidenav will appear above the content, and a backdrop will be shown. With `"push"` the sidenav will push the content of the `<mat-sidenav-container>` to the side, and show a backdrop over it. `"side"` will resize the content and keep the sidenav opened. Clicking the backdrop will close sidenavs that do not have `mode="side"`. |
28-
| `opened` | `boolean` | Whether or not the sidenav is opened. Use this binding to open/close the sidenav. |
29-
30-
### Events
31-
32-
| Name | Description |
33-
| --- | --- |
34-
| `open-start` | Emitted when the sidenav is starting opening. This should only be used to coordinate animations. |
35-
| `close-start` | Emitted when the sidenav is starting closing. This should only be used to coordinate animations. |
36-
| `open` | Emitted when the sidenav is done opening. Use this for, e.g., setting focus on controls or updating state. |
37-
| `close` | Emitted when the sidenav is done closing. |
38-
39-
### Methods
40-
41-
| Signature | Description |
42-
| --- | --- |
43-
| `open(): Promise<void>` | Open the sidenav. Equivalent to `opened = true`. Returns a promise that will resolve when the animation completes, or be rejected if the animation was cancelled. |
44-
| `close(): Promise<void>` | Close the sidenav. Equivalent to `opened = false`. Returns a promise that will resolve when the animation completes, or be rejected if the animation was cancelled. |
45-
| `toggle(): Promise<void>` | Toggle the sidenav. This is equivalent to `opened = !opened`. Returns a promise that will resolve when the animation completes, or be rejected if the animation was cancelled. |
46-
47-
48-
49-
50-
51-
### Notes
52-
53-
The `<mat-sidenav>` will resize based on its content. You can also set its width in CSS, like so:
54-
55-
```css
56-
mat-sidenav {
57-
width: 200px;
58-
}
59-
```
60-
61-
Try to avoid percent based width as `resize` events are not (yet) supported.
62-
63-
## Examples
64-
65-
Here's a simple example of using the sidenav:
66-
67-
```html
68-
<app>
69-
<mat-sidenav-container>
70-
<mat-sidenav #start (open)="closeStartButton.focus()">
71-
Start Sidenav.
72-
<br>
73-
<button mat-button #closeStartButton (click)="start.close()">Close</button>
74-
</mat-sidenav>
75-
<mat-sidenav #end position="end">
76-
End Sidenav.
77-
<button mat-button (click)="end.close()">Close</button>
78-
</mat-sidenav>
79-
80-
My regular content. This will be moved into the proper DOM at runtime.
81-
<button mat-button (click)="start.open()">Open start sidenav</button>
82-
<button mat-button (click)="end.open()">Open end sidenav</button>
83-
84-
</mat-sidenav-container>
85-
</app>
86-
```
87-
88-
For a fullscreen sidenav, the recommended approach is set up the DOM such that the
89-
`mat-sidenav-container` can naturally take up the full space:
90-
91-
```html
92-
<app>
93-
<mat-sidenav-container>
94-
<mat-sidenav mode="side" opened="true">Drawer content</mat-sidenav>
95-
<div class="my-content">Main content</div>
96-
</mat-sidenav-container>
97-
</app>
98-
```
99-
```css
100-
html, body, material-app, mat-sidenav-container, .my-content {
101-
margin: 0;
102-
width: 100%;
103-
height: 100%;
104-
}
105-
```
106-
107-
For a sidenav with a FAB (or other floating element), the recommended approach is to place the FAB
108-
outside of the scrollable region and absolutely position it.
109-
110-
```html
111-
<app>
112-
<mat-sidenav-container class="my-container">
113-
<mat-sidenav mode="side" opened="true">
114-
<button mat-mini-fab class="my-fab">
115-
<mat-icon>add</mat-icon>
116-
</button>
117-
<div class="my-scrolling-content">
118-
Lorem ipsum dolor sit amet, pede a libero aenean phasellus, lectus metus sint ut risus,
119-
fusce vel in pellentesque. Nisl rutrum etiam morbi consectetuer tempor magna, aenean nullam
120-
nunc id, neque vivamus interdum sociis nulla scelerisque sem, dolor id wisi turpis magna
121-
aliquam magna. Risus accumsan hac eget etiam donec sed, senectus erat mattis quam, tempor
122-
vel urna occaecat cras, metus urna augue nec at. Et morbi amet dui praesent, nec eu at,
123-
ligula ipsum dui sollicitudin, quis nisl massa viverra ligula, mauris fermentum orci arcu
124-
enim fringilla. Arcu erat nulla in aenean lacinia ullamcorper, urna ante nam et sagittis,
125-
tristique vehicula nibh ipsum vivamus, proin proin. Porta commodo nibh quis libero amet.
126-
Taciti dui, sapien consectetuer.
127-
</div>
128-
</mat-sidenav>
129-
<button mat-mini-fab class="my-fab">
130-
<mat-icon>add</mat-icon>
131-
</button>
132-
<div class="my-scrolling-content">
133-
Lorem ipsum dolor sit amet, pede a libero aenean phasellus, lectus metus sint ut risus, fusce
134-
vel in pellentesque. Nisl rutrum etiam morbi consectetuer tempor magna, aenean nullam nunc id,
135-
neque vivamus interdum sociis nulla scelerisque sem, dolor id wisi turpis magna aliquam magna.
136-
Risus accumsan hac eget etiam donec sed, senectus erat mattis quam, tempor vel urna occaecat
137-
cras, metus urna augue nec at. Et morbi amet dui praesent, nec eu at, ligula ipsum dui
138-
sollicitudin, quis nisl massa viverra ligula, mauris fermentum orci arcu enim fringilla. Arcu
139-
erat nulla in aenean lacinia ullamcorper, urna ante nam et sagittis, tristique vehicula nibh
140-
ipsum vivamus, proin proin. Porta commodo nibh quis libero amet. Taciti dui, sapien
141-
consectetuer.
142-
</div>
143-
</mat-sidenav-container>
144-
</app>
145-
```
146-
```css
147-
.my-container {
148-
width: 500px;
149-
height: 300px;
150-
}
151-
152-
.my-container .mat-sidenav {
153-
max-width: 200px;
154-
}
155-
156-
.my-container .mat-sidenav-content,
157-
.my-container mat-sidenav {
158-
display: flex;
159-
}
160-
161-
.my-scrolling-content {
162-
overflow: auto;
163-
}
164-
165-
button.my-fab {
166-
position: absolute;
167-
right: 20px;
168-
bottom: 10px;
169-
}
170-
```
1+
Please see the official documentation at https://material.angular.io/components/component/sidenav

‎src/lib/sidenav/sidenav.md

Lines changed: 35 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,14 @@ use three components: `<mat-sidenav-container>` which acts as a structural conta
77
and sidenav, `<mat-sidenav-content>` which represents the main content, and `<mat-sidenav>` which
88
represents the added side content.
99

10-
<!-- TODO(mmalerba): sidenav example -->
10+
<!-- example(sidenav-overview) -->
1111

1212
There are also drawer components, `<mat-drawer-container>`, `<mat-drawer-content>`, and
1313
`<mat-drawer>`, which are analogous to their sidenav equivalents. Rather than adding side content
1414
to the app as a whole, these are designed to add side content to a small section of your app. They
1515
support almost all of the same features, but do not support fixed positioning.
1616

17-
<!-- TODO(mmalerba): drawer example -->
17+
<!-- example(sidenav-drawer-overview) -->
1818

1919
### Specifying the main and side content
2020

@@ -32,7 +32,9 @@ given side.
3232
The main content should be wrapped in a `<mat-sidenav-content>`. If no `<mat-sidenav-content>` is
3333
specified for a `<mat-sidenav-container>`, one will be created implicitly and all of the content
3434
inside the `<mat-sidenav-container>` other than the `<mat-sidenav>` elements will be placed inside
35-
of it.
35+
of it.
36+
37+
<!-- example(sidenav-position) -->
3638

3739
The following are examples of valid sidenav layouts:
3840

@@ -55,7 +57,7 @@ The following are examples of valid sidenav layouts:
5557
<mat-sidenav-container></mat-sidenav-container>
5658
```
5759

58-
Anf these are examples of invalid sidenav layouts:
60+
And these are examples of invalid sidenav layouts:
5961

6062
```html
6163
<mat-sidenav-container>
@@ -90,7 +92,7 @@ The property supports 2-way binding.
9092
`<mat-sidenav>` also supports output properties for just open and just close events, The `(opened)`
9193
and `(closed)` properties respectively.
9294

93-
<!-- TODO(mmalerba): open/close example -->
95+
<!-- example(sidenav-open-close) -->
9496

9597
All of these properties and methods work on `<mat-drawer>` as well.
9698

@@ -100,13 +102,13 @@ The `<mat-sidenav>` can render in one of three different ways based on the `mode
100102

101103
| Mode | Description |
102104
|--------|-----------------------------------------------------------------------------------------|
103-
| `over` | Sidenav floats _over_ the primary content, which is covered by a backdrop |
104-
| `push` | Sidenav _pushes_ the primary content out of its way, also covering it with a backdrop |
105-
| `side` | Sidenav appears _side-by-side_ with the main content, shrinking the main content's width to make space for the sidenav. |
105+
| `over` | Sidenav floats over the primary content, which is covered by a backdrop |
106+
| `push` | Sidenav pushes the primary content out of its way, also covering it with a backdrop |
107+
| `side` | Sidenav appears side-by-side with the main content, shrinking the main content's width to make space for the sidenav. |
106108

107109
If no `mode` is specified, `over` is used by default.
108110

109-
<!-- TODO(mmalerba): modes example -->
111+
<!-- example(sidenav-mode) -->
110112

111113
`<mat-drawer>` also supports all of these same modes.
112114

@@ -120,7 +122,7 @@ Custom handling for <kbd>Esc</kbd> can be done by adding a keydown listener to t
120122
Custom handling for backdrop clicks can be done via the `(backdropClick)` output property on
121123
`<mat-sidenav-container>`.
122124

123-
<!-- TODO(mmalerba): autoclose example -->
125+
<!-- example(sidenav-disable-close) -->
124126

125127
### Setting the sidenav's size
126128

@@ -142,21 +144,35 @@ setting the `fixedInViewport` property. Additionally, top and bottom space can b
142144
`fixedTopGap` and `fixedBottomGap`. These properties accept a pixel value amount of space to add at
143145
the top or bottom.
144146

145-
<!-- TODO(mmalerba): fixed example -->
147+
<!-- example(sidenav-fixed) -->
146148

147-
### Common layout patterns
149+
### Creating a responsive layout for mobile & desktop
148150

149-
<!-- TODO(mmalerba): fill out -->
151+
A sidenav often needs to behave differently on a mobile vs a desktop display. On a desktop, it may
152+
make sense to have just the content section scroll. However, on mobile you often want the body to be
153+
the element that scrolls; this allows the address bar to auto-hide. The sidenav can be styled with
154+
CSS to adjust to either type of device.
150155

151-
#### Full-height sidenav
152-
#### Sidenav under toolbar
153-
#### Mobile sidenav
154-
#### Responsive sidenav
156+
<!-- example(sidenav-responsive) -->
155157

156158
### Accessibility
157159

158-
<!-- TODO(mmalerba): fill out -->
160+
The `<mat-sidenav>` an `<mat-sidenav-content>` should each be given an appropriate `role` attribute
161+
depending on the context in which they are used.
162+
163+
For example, a `<mat-sidenav>` that contains links
164+
to other pages might be marked `role="navigation"`, whereas one that contains a table of
165+
contents about might be marked as `role="directory"`. If there is no more specific role that
166+
describes your sidenav, `role="region"` is recommended.
167+
168+
Similarly, the `<mat-sidenav-contnet>` should be given a role based on what it contains. If it
169+
represents the primary content of the page, it may make sense to mark it `role="main"`. If no more
170+
specific role makes sense, `role="region"` is again a good fallback.
159171

160172
### Troubleshooting
161173

162-
<!-- TODO(mmalerba): fill out -->
174+
#### Error: A drawer was already declared for 'position="..."'
175+
176+
This error is thrown if you have more than one sidenav or drawer in a given container with the same
177+
`position`. The `position` property defaults to `start`, so the issue may just be that you forgot to
178+
mark the `end` sidenav with `position="end"`.

‎src/material-examples/example-module.ts

Lines changed: 55 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -86,8 +86,14 @@ import {SelectOverviewExample} from './select-overview/select-overview-example';
8686
import {SelectPanelClassExample} from './select-panel-class/select-panel-class-example';
8787
import {SelectResetExample} from './select-reset/select-reset-example';
8888
import {SelectValueBindingExample} from './select-vlaue-binding/select-value-binding-example';
89-
import {SidenavFabExample} from './sidenav-fab/sidenav-fab-example';
89+
import {SidenavDisableCloseExample} from './sidenav-disable-close/sidenav-disable-close-example';
90+
import {SidenavDrawerOverviewExample} from './sidenav-drawer-overview/sidenav-drawer-overview-example';
91+
import {SidenavFixedExample} from './sidenav-fixed/sidenav-fixed-example';
92+
import {SidenavModeExample} from './sidenav-mode/sidenav-mode-example';
93+
import {SidenavOpenCloseExample} from './sidenav-open-close/sidenav-open-close-example';
9094
import {SidenavOverviewExample} from './sidenav-overview/sidenav-overview-example';
95+
import {SidenavPositionExample} from './sidenav-position/sidenav-position-example';
96+
import {SidenavResponsiveExample} from './sidenav-responsive/sidenav-responsive-example';
9197
import {SlideToggleConfigurableExample} from './slide-toggle-configurable/slide-toggle-configurable-example';
9298
import {SlideToggleFormsExample} from './slide-toggle-forms/slide-toggle-forms-example';
9399
import {SlideToggleOverviewExample} from './slide-toggle-overview/slide-toggle-overview-example';
@@ -514,7 +520,7 @@ export const EXAMPLE_COMPONENTS = {
514520
selectorName: null
515521
},
516522
'select-no-ripple': {
517-
title: 'Select with cno option ripple ',
523+
title: 'Select with no option ripple ',
518524
component: SelectNoRippleExample,
519525
additionalFiles: null,
520526
selectorName: null
@@ -549,18 +555,54 @@ export const EXAMPLE_COMPONENTS = {
549555
additionalFiles: null,
550556
selectorName: null
551557
},
552-
'sidenav-fab': {
553-
title: 'Sidenav with a FAB',
554-
component: SidenavFabExample,
558+
'sidenav-disable-close': {
559+
title: 'Sidenav with custom escape and backdrop click behavior ',
560+
component: SidenavDisableCloseExample,
561+
additionalFiles: null,
562+
selectorName: null
563+
},
564+
'sidenav-drawer-overview': {
565+
title: 'Basic drawer ',
566+
component: SidenavDrawerOverviewExample,
567+
additionalFiles: null,
568+
selectorName: null
569+
},
570+
'sidenav-fixed': {
571+
title: 'Fixed sidenav ',
572+
component: SidenavFixedExample,
573+
additionalFiles: null,
574+
selectorName: null
575+
},
576+
'sidenav-mode': {
577+
title: 'Sidenav with configurable mode ',
578+
component: SidenavModeExample,
579+
additionalFiles: null,
580+
selectorName: null
581+
},
582+
'sidenav-open-close': {
583+
title: 'Sidenav open & close behavior ',
584+
component: SidenavOpenCloseExample,
555585
additionalFiles: null,
556586
selectorName: null
557587
},
558588
'sidenav-overview': {
559-
title: 'Basic sidenav',
589+
title: 'Basic sidenav ',
560590
component: SidenavOverviewExample,
561591
additionalFiles: null,
562592
selectorName: null
563593
},
594+
'sidenav-position': {
595+
title: 'Implicit main content with two sidenavs ',
596+
component: SidenavPositionExample,
597+
additionalFiles: null,
598+
selectorName: null
599+
},
600+
'sidenav-responsive': {
601+
title: 'Responsive sidenav ',
602+
component: SidenavResponsiveExample,
603+
additionalFiles: null,
604+
selectorName: null
605+
},
564606
'slide-toggle-configurable': {
565607
title: 'Configurable slide-toggle',
566608
component: SlideToggleConfigurableExample,
@@ -763,8 +805,14 @@ export const EXAMPLE_LIST = [
763805
SelectPanelClassExample,
764806
SelectResetExample,
765807
SelectValueBindingExample,
766-
SidenavFabExample,
808+
SidenavDisableCloseExample,
809+
SidenavDrawerOverviewExample,
810+
SidenavFixedExample,
811+
SidenavModeExample,
812+
SidenavOpenCloseExample,
767813
SidenavOverviewExample,
814+
SidenavPositionExample,
815+
SidenavResponsiveExample,
768816
SlideToggleConfigurableExample,
769817
SlideToggleFormsExample,
770818
SlideToggleOverviewExample,

‎src/material-examples/sidenav-disable-close/sidenav-disable-close-example.css

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.example-container {
2+
position: absolute;
3+
top: 0;
4+
bottom: 0;
5+
left: 0;
6+
right: 0;
7+
}

0 commit comments

Comments
 (0)