mirror of
https://github.com/ionic-team/ionic-framework.git
synced 2025-08-19 19:57:22 +08:00
docs(router): adds some docs for ion-router
This commit is contained in:
Manu Mtz.-Almeida
2
core/src/components.d.ts
vendored
2
core/src/components.d.ts
vendored
@ -2601,7 +2601,7 @@ declare global {
|
||||
namespace JSXElements {
|
||||
export interface IonRouteRedirectAttributes extends HTMLAttributes {
|
||||
from?: string;
|
||||
to?: string;
|
||||
to?: string|undefined;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@ -1,6 +1,68 @@
|
||||
# ion-route
|
||||
# ion-route-redirect
|
||||
|
||||
A redirect router can only be used in the scope of `ion-router` as a direct children of it.
|
||||
|
||||
This route has only two configurable values:
|
||||
- `from`
|
||||
- `to`
|
||||
|
||||
Their meaning is obvious under the context of a redirection, that ocurrs `from` a given URL `to` another given URL.
|
||||
|
||||
In other for a redirection to occurs the `from` path needs to be an exact match of the navigated URL.
|
||||
|
||||
## Redirection evaluation
|
||||
|
||||
An arbitrary number of redirect routes can be defined inside an `ion-router`, but only one can match.
|
||||
|
||||
Also, a redirection route WILL never redirect to another redirection router, since this could lead to infinity loops.
|
||||
|
||||
Let's say we have this two redirection rules:
|
||||
|
||||
```html
|
||||
<ion-router>
|
||||
<ion-route-redirect from="/admin" to="/login"/>
|
||||
<ion-route-redirect from="/login" to="/admin"/>
|
||||
</ion-router>
|
||||
```
|
||||
|
||||
And the user navigates to `/admin`. The router will then redirect to `/login` and stop there.
|
||||
|
||||
It WILL NOT never evalute more than one redirection rule in a roll.
|
||||
|
||||
|
||||
## Examples
|
||||
|
||||
### Simple path
|
||||
|
||||
```html
|
||||
<ion-route-redirect from="/admin" to="/login">
|
||||
```
|
||||
|
||||
This route will apply (redirect) when the user navigates to: `/admin` but it will NOT apply if the user navigates to `/admin/posts`.
|
||||
|
||||
In order to match any subpath of admin, the wildcard character (`*`) needs to be used.
|
||||
|
||||
```html
|
||||
<ion-route-redirect from="/admin/*" to="/login">
|
||||
```
|
||||
|
||||
### Redirect all routes to login
|
||||
|
||||
Redirection routes can work as guards, since that can prevent user to navigate to areas to your application based in a given condition, for example, if the user is authenticated or not.
|
||||
|
||||
|
||||
```tsx
|
||||
{!this.isLoggedIn &&
|
||||
<ion-route-redirect from="*" to="/login"/> }
|
||||
```
|
||||
|
||||
A router can be added and removed dynamically to redirect (or guard) some routes from being accessed.
|
||||
|
||||
Another approach is to modify the value of `to`, since given `to` the value of `null` or `undefined` makes disables the redirection.
|
||||
|
||||
```tsx
|
||||
<ion-route-redirect from="*" to={this.isLoggedin ? undefined : '/login'}/>
|
||||
```
|
||||
|
||||
<!-- Auto Generated Below -->
|
||||
|
||||
@ -11,10 +73,29 @@
|
||||
|
||||
string
|
||||
|
||||
A redirect route, redirects "from" a URL "to" another URL. This property is that "from" URL.
|
||||
It needs to be an exact match of the navigated URL in order to apply.
|
||||
|
||||
The path specified in this value is always an absolute path, even if the initial `/` slash
|
||||
is not specified.
|
||||
|
||||
|
||||
#### to
|
||||
|
||||
string
|
||||
|
||||
|
||||
A redirect route, redirects "from" a URL "to" another URL. This property is that "to" URL.
|
||||
When the defined `ion-route-redirect` rule matches, the router will redirect to the path
|
||||
specified in this property.
|
||||
|
||||
The value of this property is always an absolute path inside the scope of routes defined in
|
||||
`ion-router` it can't be used with another router or to perfom a redirection to a different domain.
|
||||
|
||||
Note that this is a virtual redirect, it will not cause a real browser refresh, again, it's
|
||||
a redirect inside the context of ion-router.
|
||||
|
||||
When this property is not specified or his value is `undefined` the whole redirect route is noop,
|
||||
even if the "from" value matches.
|
||||
|
||||
|
||||
## Attributes
|
||||
@ -23,16 +104,40 @@ string
|
||||
|
||||
string
|
||||
|
||||
A redirect route, redirects "from" a URL "to" another URL. This property is that "from" URL.
|
||||
It needs to be an exact match of the navigated URL in order to apply.
|
||||
|
||||
The path specified in this value is always an absolute path, even if the initial `/` slash
|
||||
is not specified.
|
||||
|
||||
|
||||
#### to
|
||||
|
||||
string
|
||||
|
||||
|
||||
A redirect route, redirects "from" a URL "to" another URL. This property is that "to" URL.
|
||||
When the defined `ion-route-redirect` rule matches, the router will redirect to the path
|
||||
specified in this property.
|
||||
|
||||
The value of this property is always an absolute path inside the scope of routes defined in
|
||||
`ion-router` it can't be used with another router or to perfom a redirection to a different domain.
|
||||
|
||||
Note that this is a virtual redirect, it will not cause a real browser refresh, again, it's
|
||||
a redirect inside the context of ion-router.
|
||||
|
||||
When this property is not specified or his value is `undefined` the whole redirect route is noop,
|
||||
even if the "from" value matches.
|
||||
|
||||
|
||||
## Events
|
||||
|
||||
#### ionRouteRedirectChanged
|
||||
|
||||
Internal event that fires when any value of this rule is added/removed from the DOM,
|
||||
or any of his public properties changes.
|
||||
|
||||
`ion-router` captures this event in order to update his internal registry of router rules.
|
||||
|
||||
|
||||
|
||||
----------------------------------------------
|
||||
|
||||
@ -6,9 +6,38 @@ import { EventEmitter } from 'ionicons/dist/types/stencil.core';
|
||||
})
|
||||
export class RouteRedirect {
|
||||
|
||||
/**
|
||||
* A redirect route, redirects "from" a URL "to" another URL. This property is that "from" URL.
|
||||
* It needs to be an exact match of the navigated URL in order to apply.
|
||||
*
|
||||
* The path specified in this value is always an absolute path, even if the initial `/` slash
|
||||
* is not specified.
|
||||
*
|
||||
*/
|
||||
@Prop() from = '';
|
||||
@Prop() to: string;
|
||||
|
||||
/**
|
||||
* A redirect route, redirects "from" a URL "to" another URL. This property is that "to" URL.
|
||||
* When the defined `ion-route-redirect` rule matches, the router will redirect to the path
|
||||
* specified in this property.
|
||||
*
|
||||
* The value of this property is always an absolute path inside the scope of routes defined in
|
||||
* `ion-router` it can't be used with another router or to perfom a redirection to a different domain.
|
||||
*
|
||||
* Note that this is a virtual redirect, it will not cause a real browser refresh, again, it's
|
||||
* a redirect inside the context of ion-router.
|
||||
*
|
||||
* When this property is not specified or his value is `undefined` the whole redirect route is noop,
|
||||
* even if the "from" value matches.
|
||||
*/
|
||||
@Prop() to: string|undefined;
|
||||
|
||||
/**
|
||||
* Internal event that fires when any value of this rule is added/removed from the DOM,
|
||||
* or any of his public properties changes.
|
||||
*
|
||||
* `ion-router` captures this event in order to update his internal registry of router rules.
|
||||
*/
|
||||
@Event() ionRouteRedirectChanged: EventEmitter;
|
||||
|
||||
componentDidLoad() {
|
||||
|
||||
@ -11,16 +11,26 @@
|
||||
|
||||
string
|
||||
|
||||
Name of the component to load/select in the navigation outlet (`ion-tabs`, `ion-nav`)
|
||||
when the route matches.
|
||||
|
||||
The value of this property is not always the tagname of the component to load,
|
||||
in ion-tabs it actually refers to the name of the `ion-tab` to select.
|
||||
|
||||
|
||||
#### componentProps
|
||||
|
||||
|
||||
|
||||
Props to pass when the `component` specified in this route load.
|
||||
|
||||
|
||||
#### url
|
||||
|
||||
string
|
||||
|
||||
Relative path that needs to match in order for this route to apply.
|
||||
|
||||
|
||||
## Attributes
|
||||
|
||||
@ -28,21 +38,33 @@ string
|
||||
|
||||
string
|
||||
|
||||
Name of the component to load/select in the navigation outlet (`ion-tabs`, `ion-nav`)
|
||||
when the route matches.
|
||||
|
||||
The value of this property is not always the tagname of the component to load,
|
||||
in ion-tabs it actually refers to the name of the `ion-tab` to select.
|
||||
|
||||
|
||||
#### component-props
|
||||
|
||||
|
||||
|
||||
Props to pass when the `component` specified in this route load.
|
||||
|
||||
|
||||
#### url
|
||||
|
||||
string
|
||||
|
||||
Relative path that needs to match in order for this route to apply.
|
||||
|
||||
|
||||
## Events
|
||||
|
||||
#### ionRouteDataChanged
|
||||
|
||||
Used internaly by `ion-router` to know when this route did change.
|
||||
|
||||
|
||||
|
||||
----------------------------------------------
|
||||
|
||||
@ -6,10 +6,28 @@ import { EventEmitter } from 'ionicons/dist/types/stencil.core';
|
||||
})
|
||||
export class Route {
|
||||
|
||||
/**
|
||||
* Relative path that needs to match in order for this route to apply.
|
||||
*/
|
||||
@Prop() url = '';
|
||||
|
||||
/**
|
||||
* Name of the component to load/select in the navigation outlet (`ion-tabs`, `ion-nav`)
|
||||
* when the route matches.
|
||||
*
|
||||
* The value of this property is not always the tagname of the component to load,
|
||||
* in ion-tabs it actually refers to the name of the `ion-tab` to select.
|
||||
*/
|
||||
@Prop() component: string;
|
||||
|
||||
/**
|
||||
* Props to pass when the `component` specified in this route load.
|
||||
*/
|
||||
@Prop() componentProps: {[key: string]: any};
|
||||
|
||||
/**
|
||||
* Used internaly by `ion-router` to know when this route did change.
|
||||
*/
|
||||
@Event() ionRouteDataChanged: EventEmitter;
|
||||
|
||||
componentDidLoad() {
|
||||
|
||||
@ -1,4 +1,48 @@
|
||||
# ion-router-controller
|
||||
# ion-router
|
||||
|
||||
`ion-router` is just a URL coordinator for the navigation outlets of ionic: `ion-nav` and `ion-tabs`.
|
||||
|
||||
That means the ion-router never touches the DOM, it does NOT show the components or emit any kind of lifecycle event, it just tell `ion-nav` and `ion-tabs` what to "show" based in the browser's URL.
|
||||
|
||||
In order to configure this relationship between components (to load/select) and URLs, ion-router uses a declarative syntax using JSX/HTML to define a tree of routes.
|
||||
|
||||
## Tree of routes
|
||||
|
||||
The way to structure navigation in an ionic app is by nesting `ion-nav`s and `ion-tabs`, for example, you have an `ion-nav` at the root, where you "push" an page that has an `ion-tabs`, then inside each tab (`ion-tab`) you might have another `ion-nav` since you want navigation independent navigation for each tab.
|
||||
|
||||
Obviously this structure is app-dependent, but in any case, nesting router-outlets (ion-nav or ion-tabs) is a common pattern. This is way the routes defined in `ion-router` are not a list of routes, but an tree.
|
||||
|
||||
Any route can have a list of nested routes:
|
||||
|
||||
```
|
||||
<ion-router>
|
||||
<ion-route component="page-tabs">
|
||||
<ion-route url="/schedule" component="tab-schedule">
|
||||
<ion-route component="page-schedule"></ion-route>
|
||||
<ion-route url="/session/:sessionId" component="page-session"></ion-route>
|
||||
</ion-route>
|
||||
|
||||
<ion-route url="/speakers" component="tab-speaker">
|
||||
<ion-route component="page-speaker-list"></ion-route>
|
||||
<ion-route url="/session/:sessionId" component="page-session"></ion-route>
|
||||
<ion-route url="/:speakerId" component="page-speaker-detail"></ion-route>
|
||||
</ion-route>
|
||||
|
||||
<ion-route url="/map" component="page-map"></ion-route>
|
||||
<ion-route url="/about" component="page-about"></ion-route>
|
||||
</ion-route>
|
||||
|
||||
<ion-route url="/tutorial" component="page-tutorial"></ion-route>
|
||||
<ion-route url="/login" component="page-login"></ion-route>
|
||||
<ion-route url="/account" component="page-account"></ion-route>
|
||||
<ion-route url="/signup" component="page-signup"></ion-route>
|
||||
<ion-route url="/support" component="page-support"></ion-route>
|
||||
</ion-router>
|
||||
|
||||
```
|
||||
|
||||
This hierarchy of routes matches the hierarchy of how `ion-tab`s and `ion-nav`s are nested together.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user