-
-
Notifications
You must be signed in to change notification settings - Fork 4.2k
/
api.ts
132 lines (104 loc) · 3.7 KB
/
api.ts
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
import { assert, deprecate } from '@ember/debug';
export interface EmberLocation {
implementation: string;
cancelRouterSetup?: boolean;
getURL(): string;
setURL(url: string): void;
replaceURL?(url: string): void;
onUpdateURL(callback: UpdateCallback): void;
formatURL(url: string): string;
detect?(): void;
initState?(): void;
destroy(): void;
}
export type UpdateCallback = (url: string) => void;
/**
@module @ember/routing
*/
/**
Location returns an instance of the correct implementation of
the `location` API.
## Implementations
You can pass an implementation name (`hash`, `history`, `none`, `auto`) to force a
particular implementation to be used in your application.
See [HashLocation](/ember/release/classes/HashLocation).
See [HistoryLocation](/ember/release/classes/HistoryLocation).
See [NoneLocation](/ember/release/classes/NoneLocation).
See [AutoLocation](/ember/release/classes/AutoLocation).
## Location API
Each location implementation must provide the following methods:
* implementation: returns the string name used to reference the implementation.
* getURL: returns the current URL.
* setURL(path): sets the current URL.
* replaceURL(path): replace the current URL (optional).
* onUpdateURL(callback): triggers the callback when the URL changes.
* formatURL(url): formats `url` to be placed into `href` attribute.
* detect() (optional): instructs the location to do any feature detection
necessary. If the location needs to redirect to a different URL, it
can cancel routing by setting the `cancelRouterSetup` property on itself
to `false`.
Calling setURL or replaceURL will not trigger onUpdateURL callbacks.
## Custom implementation
Ember scans `app/locations/*` for extending the Location API.
Example:
```javascript
import HistoryLocation from '@ember/routing/history-location';
export default class MyHistory {
implementation = 'my-custom-history';
constructor() {
this._history = HistoryLocation.create(...arguments);
}
create() {
return new this(...arguments);
}
pushState(path) {
this._history.pushState(path);
}
}
```
@class Location
@private
*/
export default {
/**
This is deprecated in favor of using the container to lookup the location
implementation as desired.
For example:
```javascript
// Given a location registered as follows:
container.register('location:history-test', HistoryTestLocation);
// You could create a new instance via:
container.lookup('location:history-test');
```
@method create
@param {Object} options
@return {Object} an instance of an implementation of the `location` API
@deprecated Use the container to lookup the location implementation that you
need.
@private
*/
create(options: { implementation: string }): EmberLocation {
let implementation = options && options.implementation;
assert("Location.create: you must specify a 'implementation' option", Boolean(implementation));
let implementationClass = this.implementations[implementation];
assert(
`Location.create: ${implementation} is not a valid implementation`,
Boolean(implementationClass)
);
deprecate(
"Calling `create` on Location class is deprecated. Instead, use `container.lookup('location:my-location')` to lookup the location you need.",
false,
{
id: 'deprecate-auto-location',
until: '5.0.0',
url: 'https://emberjs.com/deprecations/v4.x#toc_deprecate-auto-location',
for: 'ember-source',
since: {
enabled: '4.1.0',
},
}
);
return implementationClass.create(...arguments);
},
implementations: {},
};