DeepLinker

Improve this doc

DeepLinker handles registering and displaying specific views based on URLs. It's used underneath NavController so you'll never have to interact with it directly. When a new view is push'ed with NavController, the URL is updated to match the path back to this page.

Unlike traditional web apps, URLs don't dictate navigation in Ionic apps. Instead, URLs help us link to specific pieces of content as a breadcrumb. We keep the current URL updated as we navigate, but we use the NavController's push and pop, or navPush to move around. This makes it much easier to handle the kinds of complicated nested navigation native apps are known for.

We refer to our URL system as a Deep Link system instead of a Router to encourage Ionic developers to think of URLs as a breadcrumb rather than as the source of truth in navigation. This encourages flexible navigation design and happy apps all over the world.

Usage

DeepLinker can be used in the IonicModule.forRoot method, as the third parameter

imports: [
   IonicModule.forRoot(MyApp, {}, {
     links: []
  })
 ]

DeepLinker implements DeepLinkerConfig, which is an object with an array of links. So for basic example based on the blank starter, a link setup like so:

imports: [
   IonicModule.forRoot(MyApp, {}, {
     links: [
      { component: HomePage, name: 'Home', segment: 'home' }
    ]
  })
 ]

Since components/pages can be loaded anywhere in the app, DeepLinker lets you define their URL segment but doesn't require a full URL route.

So, at any point a Page becomes the active page, we just append the URL segment.

Dynamic Links

Since passing data around is common practice in an app, we can reflect that in our app's URL by using the common :param syntax:

links: [
  { component: HomePage, name: 'Home', segment: 'home' },
  { component: DetailPage, name: 'Detail', segment: 'detail/:userId' }
]

In this case, when we push to a new instance of DetailPage, the user field of the data we pass to push will be put into the URL.

The property needs to be something that can be serialized into a string by the DeepLinker.

So in a typical navCtrl.push() scenario, we'd do something like this:

pushPage(userInfo) {
  this.navCtrl.push(DetailPage, {
    'userId': userInfo.id
  })
}

Default History

While pages can be navigated to anywhere and loaded at any time, what happens when an app is launched from a deeplink while cold or suspended?

By default, the page would be navigated to in the root NavController, but often the history stack is a UX design issue that you'll want to tweak as you iterate on the UX of your app.

An example here is the App Store app on iOS. If you navigate to an app link to the App Store app, the app decides to show a single page for the app detail, and no back button. In constrast, opening an instagram link shows a back button that goes back to the profile page of the user. The point is: this back button experience is totally up to you as the designer of the app experience.

This is where defaultHistory comes in.

The defaultHistory property takes an array of components to create the initial history stack if none exists.

links: [
  { component: HomePage, name: 'Home', segment: 'home' },
  { component: DetailPage, name: 'Detail', segment: 'detail/:userId', defaultHistory: [HomePage] }
]

In this example above, if we launch the app at myapp.com/detail/4, then the user will see the DetailPage and then the back button will go to the HomePage.