Skip to content

Commit 3fd81fe

Browse files
mmalerbammalerba
committed
add examples
1 parent b387589 commit 3fd81fe

30 files changed

+453
-295
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: 54 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -95,8 +95,14 @@ import {SelectOverviewExample} from './select-overview/select-overview-example';
9595
import {SelectPanelClassExample} from './select-panel-class/select-panel-class-example';
9696
import {SelectResetExample} from './select-reset/select-reset-example';
9797
import {SelectValueBindingExample} from './select-value-binding/select-value-binding-example';
98-
import {SidenavFabExample} from './sidenav-fab/sidenav-fab-example';
98+
import {SidenavDisableCloseExample} from './sidenav-disable-close/sidenav-disable-close-example';
99+
import {SidenavDrawerOverviewExample} from './sidenav-drawer-overview/sidenav-drawer-overview-example';
100+
import {SidenavFixedExample} from './sidenav-fixed/sidenav-fixed-example';
101+
import {SidenavModeExample} from './sidenav-mode/sidenav-mode-example';
102+
import {SidenavOpenCloseExample} from './sidenav-open-close/sidenav-open-close-example';
99103
import {SidenavOverviewExample} from './sidenav-overview/sidenav-overview-example';
104+
import {SidenavPositionExample} from './sidenav-position/sidenav-position-example';
105+
import {SidenavResponsiveExample} from './sidenav-responsive/sidenav-responsive-example';
100106
import {SlideToggleConfigurableExample} from './slide-toggle-configurable/slide-toggle-configurable-example';
101107
import {SlideToggleFormsExample} from './slide-toggle-forms/slide-toggle-forms-example';
102108
import {SlideToggleOverviewExample} from './slide-toggle-overview/slide-toggle-overview-example';
@@ -612,18 +618,54 @@ export const EXAMPLE_COMPONENTS = {
612618
additionalFiles: null,
613619
selectorName: null
614620
},
615-
'sidenav-fab': {
616-
title: 'Sidenav with a FAB',
617-
component: SidenavFabExample,
621+
'sidenav-disable-close': {
622+
title: 'Sidenav with custom escape and backdrop click behavior ',
623+
component: SidenavDisableCloseExample,
624+
additionalFiles: null,
625+
selectorName: null
626+
},
627+
'sidenav-drawer-overview': {
628+
title: 'Basic drawer ',
629+
component: SidenavDrawerOverviewExample,
630+
additionalFiles: null,
631+
selectorName: null
632+
},
633+
'sidenav-fixed': {
634+
title: 'Fixed sidenav ',
635+
component: SidenavFixedExample,
636+
additionalFiles: null,
637+
selectorName: null
638+
},
639+
'sidenav-mode': {
640+
title: 'Sidenav with configurable mode ',
641+
component: SidenavModeExample,
642+
additionalFiles: null,
643+
selectorName: null
644+
},
645+
'sidenav-open-close': {
646+
title: 'Sidenav open & close behavior ',
647+
component: SidenavOpenCloseExample,
618648
additionalFiles: null,
619649
selectorName: null
620650
},
621651
'sidenav-overview': {
622-
title: 'Basic sidenav',
652+
title: 'Basic sidenav ',
623653
component: SidenavOverviewExample,
624654
additionalFiles: null,
625655
selectorName: null
626656
},
657+
'sidenav-position': {
658+
title: 'Implicit main content with two sidenavs ',
659+
component: SidenavPositionExample,
660+
additionalFiles: null,
661+
selectorName: null
662+
},
663+
'sidenav-responsive': {
664+
title: 'Responsive sidenav ',
665+
component: SidenavResponsiveExample,
666+
additionalFiles: null,
667+
selectorName: null
668+
},
627669
'slide-toggle-configurable': {
628670
title: 'Configurable slide-toggle',
629671
component: SlideToggleConfigurableExample,
@@ -835,8 +877,14 @@ export const EXAMPLE_LIST = [
835877
SelectPanelClassExample,
836878
SelectResetExample,
837879
SelectValueBindingExample,
838-
SidenavFabExample,
880+
SidenavDisableCloseExample,
881+
SidenavDrawerOverviewExample,
882+
SidenavFixedExample,
883+
SidenavModeExample,
884+
SidenavOpenCloseExample,
839885
SidenavOverviewExample,
886+
SidenavPositionExample,
887+
SidenavResponsiveExample,
840888
SlideToggleConfigurableExample,
841889
SlideToggleFormsExample,
842890
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)