/
datepicker-overview.component.html
384 lines (300 loc) · 13.8 KB
/
datepicker-overview.component.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
<p>
Datepicker will help you with date selection.
It can be used either inline with <code>NgbDatepicker</code> component or as a
popup on any input element with <code>NgbInputDatepicker</code> directive.
It also comes with the list of services to do date formatting, i18n and
<a routerLink="../calendars">alternative calendars support</a>.
</p>
<p>
We try to keep API of our components simple, but introduce extension points,
so you could enrich and reuse them.
Here is a short example of the vacation range picker that displays holidays with tooltips
and disables weekends.
</p>
<ngbd-datepicker-demo-overview class="d-block my-4"></ngbd-datepicker-demo-overview>
<!-- BASIC USAGE -->
<ngbd-overview-section [section]="sections['basic-usage']">
<p>
Datepicker can be used either inline or inside of the popup.
</p>
<ngbd-code [snippet]="snippets.basic"></ngbd-code>
<p>
In the example above the template variable <code>#d</code> will point
to the instance of the <code>NgbDatepicker</code> component in the first case.
In the second it will point to the instance of the <code>NgbInputDatepicker</code>
directive that handles the popup with inline datepicker component.
</p>
<p>
See the <a routerLink="../api" fragment="NgbDatepicker">NgbDatepicker API</a>
and the <a routerLink="../api" fragment="NgbInputDatepicker">NgbInputDatepicker API</a>
for details on available inputs, outputs and methods.
You can customize the number of displayed months, the way navigation
between months and years looks like, week numbers, etc.
</p>
<p>
If you have a very specific use case for the datepicker popup,
you could always create you own one and use the inline datepicker inside.
</p>
<h4>Handling the popup</h4>
<p>
It's up to you do decide when the datepicker popup should be opened and closed.
The API contains <code>.open()</code>, <code>.close()</code> and <code>.toggle()</code>
methods.
</p>
<p>
By default the popup element is attached after the input in the DOM.
You have also the option of attaching it to the document body by setting the
<code>[container]</code> input to <code>'body'</code>
</p>
<ngbd-code [snippet]="snippets.popup"></ngbd-code>
<p>
The popup will be closed with <code>Escape</code> key and when
a date is selected via keyboard or mouse.
It can stay open after date selection if you set <code>[autoClose]</code> input to <code>false</code>
</p>
<p>
When using a button (or any other element) to open the popup, the styling and content of the button
is left up to you. In the example above, the button is simply given the text "Toggle", but you
could also use an icon, or even group the <code>input</code> and <code>button</code> with an
<a href="https://getbootstrap.com/docs/{{ bootstrapVersion }}/components/input-group/#button-addons">input group</a>.
</p>
</ngbd-overview-section>
<!-- GETTING / SETTING A DATE -->
<ngbd-overview-section [section]="sections['getting-date']">
<p>
You have several ways of knowing when user selects a date. The date is selected
either by clicking on it, pressing <code>Space</code> or <code>Enter</code>,
typing text in the input or programmatically.
</p>
<p>
Datepicker is integrated with Angular forms and works with both reactive
and template-driven forms. So you could use <code>[(ngModel)]</code>,
<code>[formControl]</code>, <code>formControlName</code>, etc. Using
<code>ngModel</code> will allow you both to get and set selected value.
</p>
<p>
The model, however, is NOT a native javascript date, see the following
<a routerLink="./" [fragment]="sections['date-model'].fragment">Date Model</a> section for more info.
</p>
<ngbd-code [snippet]="snippets.form"></ngbd-code>
<p>
Alternatively you could use the <code>(dateSelect)</code> or <code>(select)</code> outputs.
The difference from <code>ngModel</code> is that outputs will continue emitting the same value,
if user clicks on the same date. <code>NgModel</code> will do it only once.
</p>
<ngbd-code [snippet]="snippets.selection"></ngbd-code>
</ngbd-overview-section>
<!-- DATE MODEL-->
<ngbd-overview-section [section]="sections['date-model']">
<p>
Datepicker uses <a routerLink="../api" fragment="NgbDateStruct"><code>NgbDateStruct</code></a>
interface as a model and not the native <code>Date</code> object.
It's a simple data structure with 3 fields, but note that months start with 1 (as in ISO 8601).
</p>
<ngbd-code [snippet]="snippets.dateStruct"></ngbd-code>
<p>
All datepicker APIs will consume <code>NgbDateStruct</code>, but will produce it's implementation
class <a routerLink="../api" fragment="NgbDate"><code>NgbDate</code></a> when returning dates to you.
It offers additional methods for easy date comparison, and using it together with
<a routerLink="../api" fragment="NgbCalendar"><code>NgbCalendar</code></a> will cover most
of the date-related calculations.
</p>
<ngbd-code [snippet]="snippets.date"></ngbd-code>
<h4>Adapters</h4>
<p>
You can also tell datepicker to use the native javascript date adapter (bundled with ng-bootstrap) as in the
<a routerLink="../examples" fragment="adapter">custom date adapter example</a>. For now
the adapter works only for the form integration, so for instance <code>(ngModelChange)</code>
will return a native date object. All other APIs continue to use <code>NgbDateStruct</code>.
</p>
<ngbd-code [snippet]="snippets.nativeAdapter"></ngbd-code>
<p>
You can also create your own adapters if necessary by extending and implementing the
<code>NgbDateAdapter</code> methods.
</p>
<ngbd-code [snippet]="snippets.adapter"></ngbd-code>
<h4>Input date parsing and formatting</h4>
<p>
In the case of the <code>NgbInputDatepicker</code> you should be able to parse
and format the text entered in the input. This is not as easy task as it seems,
because you have to account for various formats and locales.
For now internally there is a service that does default formatting using ISO 8601 format.
</p>
<ngbd-code [snippet]="snippets.formatter"></ngbd-code>
<p>
If the entered input value is invalid, the form model will contain the entered text.
</p>
</ngbd-overview-section>
<!-- MOVING AROUND-->
<ngbd-overview-section [section]="sections['navigation']">
<p>
Date selection and navigation are two different things.
You might have a date selected in January, but August currently displayed.
</p>
<p>
Datepicker fully supports keyboard navigation and screen readers. You can navigate
between controls using <code>Tab</code> (focus will be trapped in the popup), move
date focus with arrow keys, home, page up/down and use <code>Shift</code> modifier
for faster navigation.
</p>
<p>
With the API you can tell datepicker to initially open a specific month
via the <code>[startDate]</code> input or go to any month via the <code>.navigateTo()</code> method
</p>
<ngbd-code [snippet]="snippets.navigation"></ngbd-code>
</ngbd-overview-section>
<!-- DISABLING/LIMITING DATES-->
<ngbd-overview-section [section]="sections['limiting-dates']">
<p>
You can limit the dates available for navigation and selection using
<code>[minDate]</code> and <code>[maxDate]</code> inputs. If you don't specify
any of them, you'll have infinite navigation and the year select box
will display [-10, +10] years from currently visible month.
</p>
<p>
If you want to disable some dates for selection (ex. weekends), you have to
provide the <code>[markDisabled]</code> function that will mark certain dates
not selectable. It will be called for each newly visible day when you navigate
between months.
</p>
<ngbd-code style="position: relative; top: 0.25rem" [snippet]="snippets.disablingTS"></ngbd-code>
<ngbd-code style="position: relative; bottom: 0.25rem" [snippet]="snippets.disablingHTML"></ngbd-code>
</ngbd-overview-section>
<!-- DAY CUSTOMIZATION-->
<ngbd-overview-section [section]="sections['day-template']">
<p>
You can completely replace how each date is rendered by providing a custom template
and rendering anything you want inside. You'll get a date context available inside
the template with info on whether current date is disabled, selected, focused, etc.
</p>
<p>
For more info on what is provided in the template context,
see the <a routerLink="../api" fragment="DayTemplateContext">DayTemplateContext API</a>
</p>
<ngbd-code [snippet]="snippets.dayTemplate"></ngbd-code>
<ngb-alert class="mt-3" [dismissible]="false">
Note that before v3.3.0 there is no <code>$implicit</code> template property and you have to specify
<code>let-date="date"</code> in the template.
See <a href="https://angular.io/api/common/NgTemplateOutlet#example">$implicit example</a> in Angular documentation.
</ngb-alert>
</ngbd-overview-section>
<!-- TODAY'S DATE -->
<ngbd-overview-section [section]="sections['today']">
<p>
It is often useful to highlight a today's date in the calendar view or add a certain logic to it. Today's date
is the date returned by the <a routerLink="../api" fragment="NgbCalendar">NgbCalendar</a>'s <code>getToday()</code>
method.
</p>
<p>
We add a custom CSS class <code>.ngb-dp-today</code> on a cell that corresponds to the today's date.
We do not add any rules to it at the moment, but you can add your own if necessary.
You would see something like this in the resulting markup
</p>
<ngbd-code [snippet]="snippets.todayHTML"></ngbd-code>
<p>
You can also access this information from the <a routerLink="../api" fragment="DayTemplateContext">DayTemplateContext API</a>
if you're using a custom day template. It contains a <code>today: boolean</code> flag since v4.1.0
</p>
<ngbd-code [snippet]="snippets.todayTemplate"></ngbd-code>
</ngbd-overview-section>
<!-- FOOTER TEMPLATE -->
<ngbd-overview-section [section]="sections['footer-template']">
<p>
You can insert anything you want in a datepicker footer by providing a template.
</p>
<ngbd-code [snippet]="snippets.footerTemplate"></ngbd-code>
</ngbd-overview-section>
<!-- RANGE SELECTION -->
<ngbd-overview-section [section]="sections['range']">
<p>
The datepicker model is a single date, however you still can implement range selection
functionality. With <code>(select)</code> and <code>(dateSelect)</code> outputs you'll know
which dates are being selected and with the <code>[dayTemplate]</code> input
you can customize the way any particular date looks.
If you want to use the <code>NgbDatepickerInput</code>, you can also tell the popup
to stay open by tuning the <code>[autoClose]</code> input.
Check the <a routerLink="../examples" fragment="range">range selection example</a>
and the initial demo on this page for more details.
</p>
<p>
If you can't use the <code>NgbDatepickerInput</code> directive, you should
create your own popup and use <code>NgbDatepicker</code> inside of it. In this case
we'll handle everything related to date selection and navigation for you and you can create
a completely customized popup with any data model you want.
</p>
</ngbd-overview-section>
<!-- I18N -->
<ngbd-overview-section [section]="sections['i18n']">
<p>
Since the 2.0.0 release datepicker will use the
<a href="https://angular.io/guide/i18n#setting-up-the-locale-of-your-app">application locale</a>
if it is present to get translations of weekdays and month names. The internal service that does
translation is called <code>NgbDatepickerI18n</code> and you could provide your own implementation
if necessary.
</p>
<ngbd-code [snippet]="snippets.i18n"></ngbd-code>
<p>
The next/previous button labels can be translated using the standard Angular i18n
mechanism. For example, previous month label is extracted under the <code>ngb.datepicker.previous-month</code>
name.
</p>
</ngbd-overview-section>
<!-- Keyboard -->
<ngbd-overview-section [section]="sections['keyboard-shortcuts']">
<p>
You can customize keyboard navigation as in the <a routerLink="../examples" fragment="keyboard">custom keyboard
navigation example</a>. The default keys are as follows:
</p>
<table class="table mt-4">
<tbody>
<tr>
<td><code>Space / Enter</code></td>
<td>Selects currently focused date if it is not disabled</td>
</tr>
<tr>
<td><code>Escape</code></td>
<td>Closes the datepicker popup (unless <code>[autoClose]</code> is false)</td>
</tr>
<tr>
<td><code>Arrow(Up|Down|Left|Right)</code></td>
<td>Moves day focus inside the months view</td>
</tr>
<tr>
<td><code>Shift + Arrow(Up|Down|Left|Right)</code></td>
<td>Selects currently focused date (if it is not disabled)</td>
</tr>
<tr>
<td><code>Home</code></td>
<td>Moves focus to the the first day of currently opened first month</td>
</tr>
<tr>
<td><code>End</code></td>
<td>Moves focus to the the last day of currently opened last month</td>
</tr>
<tr>
<td><code>Shift + Home</code></td>
<td>Moves focus to the <code>minDate</code> (if set)</td>
</tr>
<tr>
<td><code>Shift + End</code></td>
<td>Moves focus to the <code>maxDate</code> (if set)</td>
</tr>
<tr>
<td><code>PageDown</code></td>
<td>Moves focus to the previous month</td>
</tr>
<tr>
<td><code>PageUp</code></td>
<td>Moves focus to the next month</td>
</tr>
<tr>
<td><code>Shift + PageDown</code></td>
<td>Moves focus to the previous year</td>
</tr>
<tr>
<td><code>Shift + PageUp</code></td>
<td>Moves focus to the next year</td>
</tr>
</tbody>
</table>
</ngbd-overview-section>