UNPKG

9.71 kBTypeScriptView Raw
1/**
2 * @hidden
3 * public link interface
4 */
5export interface IonicPageMetadata {
6 name?: string;
7 segment?: string;
8 defaultHistory?: string[];
9 priority?: string;
10}
11/**
12 * @name IonicPage
13 * @description
14 * The Ionic Page handles registering and displaying specific pages based on URLs. It's used
15 * underneath `NavController` so it will never have to be interacted with directly. When a new
16 * page is pushed with `NavController`, the URL is updated to match the path to this page.
17 *
18 * Unlike traditional web apps, URLs don't dictate navigation in Ionic apps.
19 * Instead, URLs help us link to specific pieces of content as a breadcrumb.
20 * The current URL gets updated as we navigate, but we use the `NavController`
21 * push and pop, or `NavPush` and `NavPop` to move around. This makes it much easier
22 * to handle complicated nested navigation.
23 *
24 * We refer to our URL system as a deep link system instead of a router to encourage
25 * Ionic developers to think of URLs as a breadcrumb rather than as the source of
26 * truth in navigation. This encourages flexible navigation design and happy apps all
27 * over the world.
28 *
29 *
30 * @usage
31 *
32 * The first step to setting up deep links is to add the page that should be
33 * a deep link in the `IonicPageModule.forChild` import of the page's module.
34 * For our examples, this will be `MyPage`:
35 *
36 * ```ts
37 * @NgModule({
38 * declarations: [
39 * MyPage
40 * ],
41 * imports: [
42 * IonicPageModule.forChild(MyPage)
43 * ],
44 * entryComponents: [
45 * MyPage
46 * ]
47 * })
48 * export class MyPageModule {}
49 * ```
50 *
51 * Then, add the `@IonicPage` decorator to the component. The most simple usage is adding an
52 * empty decorator:
53 *
54 * ```ts
55 * @IonicPage()
56 * @Component({
57 * templateUrl: 'main.html'
58 * })
59 * export class MyPage {}
60 * ```
61 *
62 * This will automatically create a link to the `MyPage` component using the same name as the class,
63 * `name`: `'MyPage'`. The page can now be navigated to by using this name. For example:
64 *
65 * ```ts
66 * @Component({
67 * templateUrl: 'another-page.html'
68 * })
69 * export class AnotherPage {
70 * constructor(public navCtrl: NavController) {}
71 *
72 * goToMyPage() {
73 * // go to the MyPage component
74 * this.navCtrl.push('MyPage');
75 * }
76 * }
77 * ```
78 *
79 * The `@IonicPage` decorator accepts a `DeepLinkMetadataType` object. This object accepts
80 * the following properties: `name`, `segment`, `defaultHistory`, and `priority`. All of them
81 * are optional but can be used to create complex navigation links. The `name` and `segment`
82 * values must be unique.
83 *
84 *
85 * ### Changing Name
86 *
87 * As mentioned previously, the `name` property will be set to the class name if it isn't provided.
88 * Changing the name of the link is extremely simple. To change the name used to link to the
89 * component, simply pass it in the decorator like so:
90 *
91 * ```ts
92 * @IonicPage({
93 * name: 'my-page'
94 * })
95 * ```
96 *
97 * This will create a link to the `MyPage` component using the name `'my-page'`. Similar to the previous
98 * example, the page can be navigated to by using the name:
99 *
100 * ```ts
101 * goToMyPage() {
102 * // go to the MyPage component
103 * this.navCtrl.push('my-page');
104 * }
105 * ```
106 *
107 *
108 * ### Setting URL Path
109 *
110 * The `segment` property is used to set the URL to the page. If this property isn't provided, the
111 * `segment` will use the value of source file name without the extension (`'my-page.ts'` results
112 * in segment name `'my-page'`). Since components can be loaded anywhere in the app, the `segment`
113 * doesn't require a full URL path. When a page becomes the active page, the `segment` is appended
114 * to the URL.
115 *
116 * The `segment` can be changed to anything and doesn't have to match the `name`. For example, passing
117 * a value for `name` and `segment`:
118 *
119 * ```ts
120 * @IonicPage({
121 * name: 'my-page',
122 * segment: 'some-path'
123 * })
124 * ```
125 *
126 * When navigating to this page as the first page in the app, the URL will look something like:
127 *
128 * ```
129 * http://localhost:8101/#/some-path
130 * ```
131 *
132 * However, navigating to the page will still use the `name` like the previous examples do.
133 *
134 *
135 * ### Dynamic Links
136 *
137 * The `segment` property is useful for creating dynamic links. Sometimes the URL isn't known ahead
138 * of time, so it can be passed as a variable.
139 *
140 * Since passing data around is common practice in an app, it can be reflected in the app's URL by
141 * using the `:param` syntax. For example, set the `segment` in the `@IonicPage` decorator:
142 *
143 * ```ts
144 * @IonicPage({
145 * name: 'detail-page',
146 * segment: 'detail/:id'
147 * })
148 * ```
149 *
150 * In this case, when we `push` to a new instance of `'detail-page'`, the value of `id` will
151 * in the `detailInfo` data being passed to `push` will replace `:id` in the URL.
152 *
153 * Important: The property needs to be something that can be converted into a string, objects
154 * are not supported.
155 *
156 * For example, to push the `'detail-page'` in the `ListPage` component, the following code could
157 * be used:
158 *
159 * ```ts
160 * @IonicPage({
161 * name: 'list'
162 * })
163 * export class ListPage {
164 * constructor(public navCtrl: NavController) {}
165 *
166 * pushPage(detailInfo) {
167 * // Push an `id` to the `'detail-page'`
168 * this.navCtrl.push('detail-page', {
169 * 'id': detailInfo.id
170 * })
171 * }
172 * }
173 * ```
174 *
175 * If the value of `detailInfo.id` is `12`, for example, the URL would end up looking like this:
176 *
177 * ```
178 * http://localhost:8101/#/list/detail/12
179 * ```
180 *
181 * Since this `id` will be used to pull in the data of the specific detail page, it's Important
182 * that the `id` is unique.
183 *
184 * Note: Even though the `name` is `detail-page`, the `segment` uses `detail/:id`, and the URL
185 * will use the `segment`.
186 *
187 *
188 * ### Default History
189 *
190 * Pages can be navigated to using deep links from anywhere in the app, but sometimes the app is
191 * launched from a URL and the page needs to have the same history as if it were navigated to from
192 * inside of the app.
193 *
194 * By default, the page would be navigated to as the first page in the stack with no prior history.
195 * A good example is the App Store on iOS. Clicking on a URL to an application in the App Store will
196 * load the details of the application with no back button, as if it were the first page ever viewed.
197 *
198 * The default history of any page can be set in the `defaultHistory` property. This history will only
199 * be used if the history doesn't already exist, meaning if you navigate to the page the history will
200 * be the pages that were navigated from.
201 *
202 * The `defaultHistory` property takes an array of page names. The page names are specified as statically
203 * analyzable strings (which means you must use strings and not variables or delared constants). If the
204 * parent page does not have a `name` specified in its `IonicPage` decorator its name is its class name.
205 *
206 * For example, setting the history of the detail page to the list page where the `name` is `list`:
207 *
208 * ```ts
209 * @IonicPage({
210 * name: 'detail-page',
211 * segment: 'detail/:id',
212 * defaultHistory: ['list']
213 * })
214 * ```
215 *
216 * In this example, if the app is launched at `http://localhost:8101/#/detail/my-detail` the displayed page
217 * will be the `'detail-page'` with an id of `my-detail` and it will show a back button that goes back to
218 * the `'list'` page.
219 *
220 * For a deeper example:
221 *
222 * ```ts
223 * @IonicPage({
224 * segment: 'contact-more-info',
225 * defaultHistory: ['ContactDetailPage', 'Contact']
226 * })
227 * ...
228 * export class ContactMoreInfoPage {
229 * ...
230 * }
231 * ```
232 *
233 * In this example, if the app is launched at `http://localhost:8101/#/contact/contact-more-info` the displayed page
234 * will be the `'ContactMoreInfoPage'`. It will show a back button that will go to the `'ContactDetailPage'` which
235 * will also show a back button which will go to the `'Contact'` page.
236 *
237 * An example of an application with a set history stack is the Instagram application. Opening a link
238 * to an image on Instagram will show the details for that image with a back button to the user's profile
239 * page. There is no "right" way of setting the history for a page, it is up to the application.
240 *
241 * ### Priority
242 *
243 * The `priority` property is only used during preloading. By default, preloading is turned off so setting
244 * this property would do nothing. Preloading eagerly loads all deep links after the application boots
245 * instead of on demand as needed. To enable preloading, set `preloadModules` in the main application module
246 * config to `true`:
247 *
248 * ```ts
249 * @NgModule({
250 * declarations: [
251 * MyApp
252 * ],
253 * imports: [
254 * BrowserModule,
255 * IonicModule.forRoot(MyApp, {
256 * preloadModules: true
257 * })
258 * ],
259 * bootstrap: [IonicApp],
260 * entryComponents: [
261 * MyApp
262 * ]
263 * })
264 * export class AppModule { }
265 * ```
266 *
267 * If preloading is turned on, it will load the modules based on the value of `priority`. The following
268 * values are possible for `priority`: `"high"`, `"low"`, and `"off"`. When there is no `priority`, it
269 * will be set to `"low"`.
270 *
271 * All deep links with their priority set to `"high"` will be loaded first. Upon completion of loading the
272 * `"high"` priority modules, all deep links with a priority of `"low"` (or no priority) will be loaded. If
273 * the priority is set to `"off"` the link will not be preloaded. Setting the `priority` is as simple as
274 * passing it to the `@IonicPage` decorator:
275 *
276 * ```ts
277 * @IonicPage({
278 * name: 'my-page',
279 * priority: 'high'
280 * })
281 * ```
282 *
283 * We recommend setting the `priority` to `"high"` on the pages that will be viewed first when launching
284 * the application.
285 *
286 */
287export declare function IonicPage(_config?: IonicPageMetadata): ClassDecorator;