Upgrade Notes

This page contains the notes for upgrades

Tooling

1. ionic serve doesn't work for now. Use ng serve.
2. ionic v4 depends on angular and rxjs 6.x.

Upgrade

• Installed ionic cli (rc) npm i -g ionic@rc
• Created a new project ionic start v4-ion-meetups tabs --type=angular

The following steps copy listed directories from v3 project to listed destinations in v4 project.

• Copied /src/pages to /src/app/pages
• Copied /src/models to /src/app/models
• Copied /src/providers to /src/app/providers.
• Copied /src/utils to /src/app/utils.

Now getting error Can't resolve module ionic-angular. Fixing this.

• Breaking From all the individual pages' modules, replaced IonicPageModule and IonicPageModule.forRoot... with IonicModule.

• Replaced ionic-angular with @ionic/angular.

• Breaking NavController and NavParams aren't compatible with angular routing in v4. Use angular's Router and ActivatedRoute for similar use.

• Breaking There's no ViewController in v4. If you're using it for modals, replace it with ModalController from @ionic/angular.

• Breaking ActionSheetController#create now returns a promise for the action sheet, instead of action sheet itself.

• Breaking Major ionViewDidLoad lifecycle callback doesn't work in v4. Since it's just angular routing, use ngOnInit.

Upgrading routes:

1. Getting the container tabs page to work first

• Breaking Added a routes definition with only Tabs page, and blank redirect routes to start with. Also imported the routes in TabsPageModule.

const routes: Routes = [
  {
    path: 'tabs',
    component: TabsPage
  },
  {
    path: '',
    redirectTo: '/tabs',
    pathMatch: 'full'
  }
];

Getting error that root is not a known property of ion-tab. Expected since ion-tab has a different API/usage in v4.

• Breaking Renamed tabIcon to icon for ion-tab element.
• Breaking Replaced [root]... with href= attribute.
• Breaking Renamed tabTitle to label.
• Breaking ion-tab also needs a child element ion-router-outlet. This new element takes a name attribute which helps in specifying which components go in which tab while writing routes.

This gets the tab page working, but obviously shows blank tab content.

Getting about page loading

1. In about.module.ts, added entry component with AboutPage component. Also, added a RouterModule.forChild import to the module with blank path, AboutPage component and about outlet. This outlet tells this route which router outlet to target when loading. Since we're lazy loading, we need to specify this outlet in both - tabs module and about page module.

2. In tabs.module.ts, add a new child route for main tabs route:

  {
    path: 'tabs',
    component: TabsPage,
    children: [
      {
        path: 'about',
        outlet: 'about',
        loadChildren: '../about/about.module#AboutPageModule'
      }
    ]
  }

This allows lazy loading AboutPage component into ion-router-outlet with the name about inside tabs.html.

I've observed it would have been better if I brought over one page at a time into this project. Even though I'm really only working to get one page running at a time, all pages throw upgrade related error which have to be fixed/commented to get them out of the way until I can get to their pages.

Getting Users list and details page loading

1. Follow instructions for About page from above, except for users.module.ts in this case.
2. Breaking ion-navbar isn't present in v4. Replace it with ion-toolbar. Also, if we need back button, we need to add it manually (ion-navbar took care of that in v3). Throw the following code inside the ion-toolbar for a button:

    <ion-buttons slot="start">
      <ion-back-button text="Users" defaultHref="/tabs/(users:user-list)"></ion-back-button>
    </ion-buttons>

3. Breaking [item-start] and [item-end] attributes aren't available on ionic elements in v4.Replace it with slot="start" and slot="end" respectively instead.
4. Breaking We need to replace code for navigation to another page (user detail). Replace

this.navCtrl.goForward('users-detail-page', {user});

with

this.router.navigateByUrl(`tabs/(users:user-detail/${user.email})`);

1. Add import for RouterModule.forChild in user-detail.module.ts.
2. Add new route with parameters to tabs.module.ts. Looks like this:

{
  name: 'user-detail/:email,
  outlet: 'users',
  loadChildren: '../user-detail/user-detail.module#UserDetailPageModule'
}

3. Breaking In user-detail.ts, we need to update how we're reading parameter. We can't use navParams.get anymore, since we're using angular's native routing. Inject ActivatedRoute dependency in component, and use this.route.snapshot.paramMap.get('email') for this.

Note: Breaking With v3 ionic router, it was possible to send entire objects as route parameters. That's not an option since parameters are reflected in url. So either A. the code needs to be updated to communicate via primitive params or B. use service for communication. Update v3 app to use primitive params in routes before beginning upgrade

Getting events page, dialog and event-details page loading

1. Configure the routes etc. similar to previous pages.
2. Breaking In action sheet's parameter, title property is renamed to header.
3. <ion-fab right bottom> becomes <ion-fab vertical="bottom" horizonal="end">.
4. The <button> inside ion-fab is replaced by <ion-fab-button>.
5. <ion-fab> now lies outside <ion-content>.
6. If you have <button ion-button> elements inside <ion-buttons>, replace them with <ion-button>.

Applying styles to components

Since we're not using Angular, the way ionic pages had an element in v3, which you could access in the style file is no longer the case. So previously we had:

page-about {
  .about-page {
    &__contributors {
      .details {
          margin-left: 10px;
      }
    }
  }
}

Where ionic used to have this page-about selector already put in the stylesheet. Now, you can either get rid of this parent selector, or if you had styles to this root page selector, you can use :host instead. I.e.

:host {
  .about-page {
    &__contributors {
      .details {
          margin-left: 10px;
      }
    }
  }
}