Skip to content

Commit 3a204da

Browse files
devversionjelbourn
devversion
authored and
jelbourn
committed
docs: create migration guide for v9 hammer migration (#17752)
1 parent 1512721 commit 3a204da

File tree

1 file changed

+142
-0
lines changed

1 file changed

+142
-0
lines changed

‎guides/v9-hammerjs-migration.md

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# V9 HammerJS migration
2+
3+
Angular Material, as of version 9, no longer requires HammerJS for any component. Components which
4+
previously depended on HammerJS no longer provide a [`HAMMER_GESTURE_CONFIG`][1] that will
5+
enable use of HammerJS events in templates.
6+
7+
Additionally the `GestureConfig` export from `@angular/material/core` has been marked as
8+
deprecated and will be removed in version 10.
9+
10+
### Why is a migration needed?
11+
12+
Since HammerJS previously was a requirement for a few Angular Material components, projects might
13+
have installed `HammerJS` exclusively for Angular Material. Since HammerJS is no longer needed when
14+
updating to v9, the dependency on HammerJS can be removed if it's not used directly in the
15+
application.
16+
17+
In some cases, projects use HammerJS events in templates while relying on Angular Material
18+
modules to set up the HammerJS event plugin. Since this is no longer the case in version 9,
19+
such projects need to manually configure the HammerJS event plugin in order to continue using
20+
these HammerJS events.
21+
22+
### What does the migration do?
23+
24+
The migration automatically removes HammerJS from the project if HammerJS is not used.
25+
26+
Additionally, Angular Material's `GestureConfig` (now deprecated) defined custom HammerJS gestures.
27+
If the application directly uses any of these gestures, the migration will introduce a new
28+
application-specific configuration for these custom gestures, removing the dependency on Angular
29+
Material's `GestureConfig`.
30+
31+
Finally, if the application uses any of the custom HammerJS gestures provided by Angular Material's
32+
`GestureConfig`, or the default HammerJS gestures, the migration will add an import for Angular's
33+
new `HammerModule`, which enabled HammerJS event bindings. These bindings were previously enabled
34+
by default in Angular versions 8 and below.
35+
36+
If your application provides a custom [`HAMMER_GESTURE_CONFIG`][1] and also references the
37+
deprecated Angular Material `GestureConfig`, the migration will print a warning about
38+
ambiguous usage. The migration cannot migrate the project automatically and manual changes
39+
are required. Read more [in the dedicated section](#The-migration-reported-ambiguous-usage-What-should-I-do).
40+
41+
### How does the schematic remove HammerJS?
42+
43+
HammerJS can be set up in many ways. The migration handles the most common cases, covering
44+
approaches recommended by Angular Material in the past. The migration performs the following steps:
45+
46+
*1\.* Remove `hammerjs` from the project `package.json`.
47+
```json
48+
{
49+
"dependencies": {
50+
"hammerjs": "..."
51+
}
52+
}
53+
```
54+
*2\.* Remove script imports to `hammerjs` in the `index.html` file.
55+
```html
56+
<script src="https://my-cdn.io/hammer.min.js"></script>
57+
```
58+
*3\.* Remove [side-effect imports][2] to `hammerjs`.
59+
```typescript
60+
import 'hammerjs';
61+
```
62+
63+
The migration cannot automatically remove HammerJS from tests. Please manually clean up
64+
the test setup and resolve any test issues. Read more in a
65+
[dedicated section for test migration](#How-to-migrate-my-tests)
66+
67+
### How do I migrate references to the deprecated `GestureConfig`?
68+
69+
The `GestureConfig` can be consumed in multiple ways. The migration covers the most common cases.
70+
The most common case is that an `NgModule` in your application directly provides `GestureConfig`:
71+
72+
```typescript
73+
import {GestureConfig} from '@angular/material/core';
74+
75+
@NgModule({
76+
...
77+
providers: [
78+
{provide: HAMMER_GESTURE_CONFIG, useClass: GestureConfig}
79+
],
80+
})
81+
export class AppModule {}
82+
```
83+
84+
If this pattern is found in the project, it usually means that a component relies on the
85+
deprecated `GestureConfig` in order to use HammerJS events in the template. If this is the case,
86+
the migration automatically creates a new gesture config which supports the used HammerJS
87+
events. All references to the deprecated gesture config will be rewritten to the newly created one.
88+
89+
If no event from the deprecated config is used, the provider declaration can be safely removed
90+
from the module. This is automatically done by the migration.
91+
92+
There are other patterns where the deprecated `GestureConfig` is extended, injected or used
93+
in combination with a different custom gesture config. These patterns cannot be handled
94+
automatically, but the migration will report such patterns and ask for manual cleanup.
95+
96+
<a name="test-migration"></a>
97+
### How to migrate my tests?
98+
99+
Components in your project might use Angular Material components which previously depended
100+
on HammerJS. There might be unit tests for these components which also test gesture functionality
101+
of the Angular Material components. For such unit tests, find all failing gesture tests. These
102+
might need to be reworked to dispatch proper events to simulate gestures, or need to be deleted.
103+
Specifically gesture tests for the `<mat-slide-toggle>` should be removed. This is because the
104+
`<mat-slide-toggle>` no longer supports gestures.
105+
106+
If some unit tests depend on the deprecated Angular Material `GestureConfig` to simulate gesture
107+
events, the reference should be either removed and tests reworked to use DOM events, or the
108+
reference should be changed to the new gesture config created by the migration.
109+
110+
If HammerJS has been removed by the migration from the project, you might able to need to
111+
clean up test setup that provides HammerJS. This is usually done in the test main file (usually
112+
in `src/test.ts`) where `hammerjs` is imported.
113+
114+
```typescript
115+
import 'hammerjs';
116+
```
117+
118+
<a name="what-to-do-ambiguous-usage"></a>
119+
### The migration reported ambiguous usage. What should I do?
120+
121+
**Case 1**: It detected that a HammerJS event provided by the deprecated `GestureConfig` is
122+
used in a component template. This is because the migration relies on static analysis to detect
123+
event bindings and can never guarantee that a event binding is bound to the Hammer gesture
124+
plugin, or to an actual `@Output`. For example:
125+
126+
```html
127+
<image-rotator (rotate)="onRotate()"></image-rotator>
128+
```
129+
130+
In the example above, `rotate` could be an event from the deprecated `GestureConfig`, or an
131+
`@Output` from `<image-rotator>`. The migration warns about this to raise awareness that it
132+
might have _incorrectly kept_ HammerJS. Please manually check if you can remove HammerJS.
133+
134+
**Case 2**: The deprecated Angular Material `GestureConfig` is used in combination with a
135+
custom [`HAMMER_GESTURE_CONFIG`][1]. This case is ambiguous because the migration is unable
136+
to detect whether a given HammerJS event binding corresponds to the custom gesture config, or to
137+
the deprecated Angular Material gesture config. If such a warning has been reported to you, check
138+
if you can remove references to the deprecated `GestureConfig`, or if you need to handle the events
139+
provided by the deprecated gesture config in your existing custom gesture config.
140+
141+
[1]: https://v9.angular.io/api/platform-browser/HammerGestureConfig
142+
[2]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#Import_a_module_for_its_side_effects_only

0 commit comments

Comments
 (0)