diff --git a/core/src/components.d.ts b/core/src/components.d.ts
index 84fdcb4bce..d5d1f528b5 100644
--- a/core/src/components.d.ts
+++ b/core/src/components.d.ts
@@ -2601,7 +2601,7 @@ declare global {
namespace JSXElements {
export interface IonRouteRedirectAttributes extends HTMLAttributes {
from?: string;
- to?: string;
+ to?: string|undefined;
}
}
}
diff --git a/core/src/components/route-redirect/readme.md b/core/src/components/route-redirect/readme.md
index 457fe32fe3..c980ecc0d6 100644
--- a/core/src/components/route-redirect/readme.md
+++ b/core/src/components/route-redirect/readme.md
@@ -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
+
+
+
+
+```
+
+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
+
+```
+
+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
+
+```
+
+### 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 &&
+ }
+```
+
+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
+
+```
@@ -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.
+
----------------------------------------------
diff --git a/core/src/components/route-redirect/route-redirect.tsx b/core/src/components/route-redirect/route-redirect.tsx
index 728d842088..22849246bd 100644
--- a/core/src/components/route-redirect/route-redirect.tsx
+++ b/core/src/components/route-redirect/route-redirect.tsx
@@ -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() {
diff --git a/core/src/components/route/readme.md b/core/src/components/route/readme.md
index 9c9e5b7f7d..41316f02f0 100644
--- a/core/src/components/route/readme.md
+++ b/core/src/components/route/readme.md
@@ -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.
+
----------------------------------------------
diff --git a/core/src/components/route/route.tsx b/core/src/components/route/route.tsx
index e21bc209c1..df7b448e9c 100644
--- a/core/src/components/route/route.tsx
+++ b/core/src/components/route/route.tsx
@@ -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() {
diff --git a/core/src/components/router/readme.md b/core/src/components/router/readme.md
index 4619355fc9..e624943a6d 100644
--- a/core/src/components/router/readme.md
+++ b/core/src/components/router/readme.md
@@ -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:
+
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+This hierarchy of routes matches the hierarchy of how `ion-tab`s and `ion-nav`s are nested together.
+