DEV Community: Reconcept

Upgrading from Capacitor 2 in 2024 - Lessons Learned

Gerhard — Wed, 17 Apr 2024 13:31:50 +0000

Looking back on the project, there were a few lessons learned and hopefully we can help you with avoiding these mistakes

Estimations

When starting the migration project, we estimated that it would take longer than 1 sprint (we do 2 weeks) to fully migrate the application. A big investment, but worth it in the long run.
It turned out to actually be a lot shorter than that; it took 1 FTE about 1 week + some extra for reviews to eventually migrate the project.
The fact that we could upgrade to Capacitor 4 & 5 without having to upgrade all plugins, made progress a lot
faster.

The biggest trouble we got was from the FileReader, where we had a ZoneJS instance and a Capacitor instance. This was very tough to find out, but at one point the dots got connected and we found a solution to use.

Could we have done it better?

Probably, but not by a lot. When we started the project the target was to finish. We might have been better off with some more Proof of Concepts and prototypes to see how the migration would go. That would have given us a better idea and estimation on how to tackle it fully.

But in the end we are very happy with how the migration has gone and we will be better focused on future releases so we’ll have an easier time upgrading again!

Upgrading from Capacitor 2 in 2024 - Part 3: OneSignal

Gerhard — Wed, 17 Apr 2024 13:31:44 +0000

Another big plugin we needed to upgrade was the OneSignal notifications plugin. We were still at version 2 for this plugin, with 5 being the latest, so we knew we had some work to do here.

Unfortunately the official documentation only showed how to initialize and handle a simple notification and we could not find how to migrate the other features we use, like enabling or disabling notifications from the app.

We tried looking at other solutions, like the Capacitor push-notifications-plugin. It seemed to have everything we needed, but required a full rework of all the code in the app and some backend work too. This was too big of a change to do at that moment, so we had to do more research

Finding the treasure

But after some digging in the GitHub repository, we found the migration guide.
Following this guide, we could upgrade the plugin to the latest version, and the only problem we encountered was actually us not fully understanding how OneSignal works with fresh installs.

Fresh installs equals new subscription

We wanted to test sending a notification to a user, so we found our test device in the subscriptions with OneSignal,
and marked it as a test account. We could then send a test notification, and it showed up on the device.

So we continued implementing the enabling and disabling of the notifications from the app. When testing this with our marked test device, we saw no updates happening to the subscription! A lot of frustrations, verbose logging and installations later, we noticed that the UUID of the new install did not match the UUID of the test account!

So for every new installation, which happens with a rebuild, a new subscription id is used in OneSignal. So we just had to mark the new subscription id as a test account, and the notification arrived.

Upgrading from Capacitor 2 in 2024 - Part 4: Minor plugins

Gerhard — Wed, 17 Apr 2024 13:31:38 +0000

There were a few minor plugins that also needed updating:

Camera
Rating
Biometrics

Camera

Capacitor provides a Camera plugin, which we could easily migrate to from the Cordova plugin.
We only had to match the Cordova CameraOptions to the Capacitor ImageOptions, and we were good to go. Both plugins returned the same result, a path to the file. This meant no further changes necessary.

Easy work, hopefully the other plugins coöporate as well.

RateApp

As all apps do, we also annoy ask the user for a review whenever possible. But both Android and iOs limit the amount of requests an app can do for a review. For instance, on iOS:

No matter how many times you call the API, the system will only show up to a maximum of 3 prompts to the same user in a 365-day period.

We used cordova-launch-review, which started in 2015 and stopped development in 2020. There was a lot of code recommended by the plugin to check if the user was actually requested for a review, and some management for asking again.

The new RateApp has a very simple recommendation:

import { RateApp } from 'Capacitor-rate-app';
RateApp.requestReview();

So we removed all the surrounding code for the previous plugin, and now use RateApp as recommended.

Biometrics

We offer the feature to the user to use biometric validation, so they can unlock or validate documents using their fingerprint or face.
We store a PIN with this biometric authentication, which we send to the backend when validation is needed.

The Cordova plugin we used was a forked branch of cordova-plugin-keychain-touch-id. This forked branch had some required updates to work with the newer Android versions.

The first plugin we tried was Capacitor-biometric-auth, but after implementing the first steps we found out that we couldn’t store the PIN with the authentication, so we had to find something else.

Capacitor-native-biometric provided the solution we needed. Although they intended to store a username/password with the biometric authentication, we just put the PIN in the password field which worked perfectly.

The old plugin could tell us if the user had stored a value, without requiring unlocking it. This was not possible in the new plugin, which always requires unlocking before accessing the value. This means we had to do some work, and had to add a feature where we track separately if the user has set the biometrics.

Unfortunately we can’t migrate the users that use the old plugin to the new plugin. The new plugin stores the PIN in a different way, so with the update it wouldn’t work anymore. So we added a popup notification for the users that uses their biometrics that they need to provide access again.

Upgrading from Capacitor 2 in 2024 - Part 2: Files

Gerhard — Wed, 17 Apr 2024 09:06:07 +0000

Finally, we could start with upgrading the plugins from Cordova to Capacitor.

The first plugins we chose to upgrade all had to do with handling files. In the application you can attach files to your portfolio, which of course can be chosen from the device.

We had several plugins to manage this in Cordova, even specific ones for Android and iOS:

@ionic-native/file-chooser (android)
@ionic-native/file-picker (iOS)
@ionic-native/image-picker (for iOS & android)

In Capacitor, these were all replaced using Capacitors’ Filesystem plugin. This plugin had all the features we needed, and works basically the same, by returning a path to where the file was located on the devices.

Troubles ahead

The trouble began when we wanted to upload the selected file to our back-end, to connect them to the portfolio. We use S3 as storage, and have written code that uses the JavaScript File interface to upload the file. But the plugins all return a string to the file on the device, not the actual file itself.

We had a different Cordova plugin to handle this @ionic-native/file, that added a function called resolveLocalFileSystemURL. This returns a JavaScript File from the given path, which we used in our code to upload.

Here again, Capacitors’ Filesystem came to the rescue. The readFile function returns a base64 encoded string from the file contents. Then using some ‘inspiration’ from stack overflow, we created a Blob from which we can create the File instance we need for our existing code.

This all made sense in theory, but when executing the code we found that the contents of the file were always empty.
We went deep into the plugin’s code to see what was going on, and we saw that the readFile function uses the FileReader from the browser the app is running in But because the Capacitor plugins run outside of the Angular zone, we’d get a different instance for this FileReader than the one we get from ZoneJS to upload the file to the S3 storage!.

Patching FileReader

We found some help on the internet, and now we patch the FileReader constructor to always use the instance used by ZoneJS (if present). Lovely stuff.
The last plugins concerning files were the FileOpener and PhotoViewer.

The FileOpener requests the OS for an app to open the file, and we found that the plugin from the Capacitor community @Capacitor-community/file-opener was a near drop-in replacement for the Cordova version.
For the photo viewer, we also chose a community plugin: @Capacitor-community/photoviewer. This one actually had quite a few installation steps, because the plugin is written in Kotlin, but the steps were clear to follow and the plugin worked immediately.

The upgrading of the file handling in the app had some up’s and downs. Some plugins were easily replaced, but the whole FileReader issue caused a lot of headaches. Some luck was needed to realise the problem with the multiple instances, but the fix/hack works like a dream/nightmare.

If all plugins cause problems like this, we might have a bumpier road ahead of us then we’d like.

Upgrading from Capacitor 2 in 2024 - Part 1

Gerhard — Wed, 17 Apr 2024 09:05:50 +0000

The first step was trying to estimate the amount of work that needed to be done. This resulted in the following plan:

#1

Lay the ground work

update Capacitor to v4, fix plugins that are not compatible
update Capacitor to v5 (latest), fix plugins that are not compatible.

#2

Then update rest of plugins:

FilePicker
FileOpener
Photoviewer
Camera
App Review
Biometrics
Notifications

We weren’t sure if we could even build the app while upgrading to test the individual parts, so even the first step could become a huge hurdle before we even got to see the results. For this reason we estimated this could take over 1 sprint to do, but if we don’t start now it won’t become any easier either.

So we just started and would see what happens. We have the daily standup for check-ins, to see how it’s going and if we need to change our approach or maybe get some extra help.

Migration to Capacitor 4.

The Capacitor CLI provides a migration tool that can be run to easily update the Android & iOS specific files, so we don’t have to manually go through the platform specific configuration files. We followed the instructions in the Updating to 4.0 guide, the files were updated and the only thing left to do was try to start up the app and see what needed to be fixed.

The next step was upgrading the local Java version from 8 to 11, which was required for Android.
Then we needed to migrate from @Capacitor/storage to the new @Capacitor/preferences and thought, this is where the ‘fun’ begins.

But luckily the API of the new Preferences and Storage were basically the same, and we were happily surprised that the app immediately started and we were able to use the outdated Cordova plugins with the new version
This means we can easily migrate each plugin and test it without having to change the entire application.

Hopefully the migration to the next version is just as easy…

Migration to Capacitor 5: A New Hope

For the migration to the next major version, we followed the next migration guide Updating to 5.0. However, we also noticed a page Updating plugins to 5.0. This page described the things the plugin developers needed to do to upgrade to the latest Capacitor version.

Surely this would mean our smooth sailing would be over?

We started the migration using the migrate command from the CLI, updated Java to version 17 and started the application.

Again, the build succeeded and the application started. At first a sigh of relief, but when we tried to login to the application we were met with an ‘invalid credentials’ error.
After some digging, we found that the ionic-native/http plugin we use for logging in, could not handle the secure cookies. This was due to a change in the android manifest file by the migration:
from:

<data android:scheme="nl.reconcept.portfolio.universal"/>

<data android:host="reconcept.app" android:scheme="https"/>

To fix this, we used the Capacitor provided plugin CapacitorHttp, which has built-in cookie handling. Luckily, changing the code to use the new plugin did not have any big complications and when it was done we were able to login again.
Our expected struggles did not happen, which allowed us to update the features one by one. This was very good news and gave us hope that the rest of the project would be a lot less work.

But, when we started work on upgrading the Cordova plugins to their Capacitor counterparts, we were met with some tricky differences.

Upgrading from Capacitor v2 in 2024

Gerhard — Wed, 17 Apr 2024 09:05:34 +0000

This is the story of how we moved our Ionic app from Cordova + Capacitor 2/3 to the latest Capacitor 5 + Capacitor plugins.

First some background

We have a simplified version of our web application available on mobile through the App Stores, which allows our users to quickly add to their portfolio.

The app is built in Ionic, using a mix of Cordova and Capacitor plugins to communicate with the native systems. To name a few systems that we use:
Filesystem to handle file interactions like selecting, uploading and viewing.
Camera plugin is used to set a profile picture
Biometric features of the phone to quickly unlock the app and validate documents.

Furthermore we send notifications using OneSignal, and need to listen for these in the background while the app is not running.

Why not upgrade sooner?

The Cordova plugins have always worked, and we never really required more features from the phones so the plugins were not kept up to date. It was on our radar, but it never had enough priority to do something about. If it ain’t broken, don’t fix it, right?

Then the unthinkable happened, we wanted to build a new feature using something native: a badge on the app icon showing actionable items for the user. We quickly found a plugin that could provide this feature, but it was built for the latest Capacitor version, while we were almost 3 major versions behind.

This gave us the incentive to update the used Capacitor version to the latest and replace the plugins from Cordova with their new Capacitor counterparts.

In this multipart series, we’ll go into our experiences while upgrading the app from ancient history to modern times.

Parts

[tiu] Container Queries

Gerhard — Tue, 05 Dec 2023 06:26:56 +0000

In this edition of Today I Used: Container Queries. How can this feature help overcome the limitations of media queries?

The situation

A while back we got feedback from a user that they were unable to access an important feature in our application.
We found that on smaller screens, a part of the application would fall outside of the available screen area. Important controls were not available anymore for the user, unless they zoomed out a lot.

A quick solution would be to add the css-rule overflow-x: scroll and be done with it, but there is probably a nicer way to do this.

The solution?

We started with using @media queries to show shorter texts and move information behind tooltips which can be activated using a hover. This made enough room so the application is fully visible on smaller screens.

This seemed to solve the issue, except for a few problems: we have a toggleable side navigation, which reduces the available space by about 250px. When expanded, it would mess with the @media queries' breakpoints and show a scrollbar.

Also, when the user zooms in, the window size stays the same but the content grows in size. The @media queries won't trigger and the scroll bar is shown.

Lastly we had to choose different breakpoints then our global ones, since the breakpoints were dependant on the content in the screen. These breakpoints felt a bit random, since it was hard to pick 'nice' values.

Container queries to the rescue

@container queries work the same as @media queries but instead of using the entire window as a measurement, you can target an HTML element to listen to.

.table-container {
  container-type: inline-size; // use the inner dimensions
  container-name: role-table;  // give it a name, to reference 
  overflow-x: auto;            // scroll, if needed
}

Then we can target this container using @container <<container-name>. The following code toggles the short and long header names.

@container role-table (max-width: 750px) {
  .table {
    .short-header {
      display: table-cell;
    }

    .long-header {
      display: none;
    }
  }
}

@container role-table (min-width: 750px) {
  .table {
    .short-header {
      display: none;
    }

    .long-header {
      display: table-cell;
    }
  }
}

Now the breakpoints activate correctly when the sidebar is toggled, since this reduces the available width of the container. Also we can be specific about the available size of the specified container, and not have seemingly random @media query breakpoints in the codebase.

Extra cool feature

Another cool feature of @container-queries is that they provide container query length units. These are special units that specify a length relative to the dimensions of a query container.

The container query length units are:

cqw: 1% of a query container's width
cqh: 1% of a query container's height
cqi: 1% of a query container's inline size
cqb: 1% of a query container's block size
cqmin: The smaller value of either cqi or cqb
cqmax: The larger value of either cqi or cqb

This means you can smoothly change the size of for instance the font, based on the container size.

@container role-table (min-width: 700px) {
  .title {
    font-size: max(1.5em, 1.23em + 2cqi);
  }
}

More info

Reconcept Dev Blogs

Gerhard — Mon, 20 Nov 2023 13:28:26 +0000

Welcome to the Reconcept Dev Blogs.

This is the start of a series where we will explain how the development of our Portfolio platform unfolds.

We will discuss smaller solutions, as well as larger projects and how we approached them. Additionally, we would like to share interesting things we have come across as developers.

We are also administrators of the Frontend Developers Groningen meetup. We strive to organize a meetup once per quarter to share knowledge and connect with fellow developers.

About Reconcept

At Reconcept, we create a Portfolio platform focused on medical education. The Portfolio provides the ability to capture practical feedback and link it to various topics such as skills or themes.

We have split the platform into different applications:

Portfolio, the main application
Login, a separate login application for OAuth
Support, our backoffice
Portfolio App, a mobile version available in the App Stores
Quality Dashboard, an additional application for ensuring education quality through the PDCA cycle.

Tech Stack

The frontend(s) are built with Angular, with Ionic for the mobile app.
The backend is built with Ruby on Rails.

Reconcept Dev Blogs (Dutch)

Gerhard — Mon, 20 Nov 2023 13:28:16 +0000

Welkom bij de Reconcept Dev Blogs.

Dit is de start van een serie waarbij we uit de doeken doen hoe het ontwikkelen van ons Portfolio platform eraan toe gaat.

We gaan het hebben over kleinere oplossingen, maar ook over grotere projecten en hoe we die hebben aangepakt. Daarnaast willen we graag dingen delen die we als developers interessant vonden die we zijn tegengekomen.

Ook zijn we beheerders van de Frontend Developers Groningen meetup. We proberen 1x per kwartaal een meetup te organiseren om kennis te delen en te connecten met onze mede developers.

Over Reconcept

Bij Reconcept maken we een Portfolio platform gericht op de medische opleidingen. Het Portfolio biedt de mogelijkheid om praktijkgerichte feedback vast te leggen, en deze te koppelen aan verschillende onderwerpen zoals vaardigheden of thema's.

We hebben het platform opgesplitst in verschillende applicaties:

Portfolio, de hoofdapplicatie
Login, aparte login applicatie voor OAuth
Support, onze backoffice
Portfolio App, mobiele versie beschikbaar in de App Stores
Kwaliteitsdashboard, een extra applicatie waarmee de opleiding via de PDCA cyclus en kwaliteit kan waarborgen.

Tech Stack

De frontend(s) zijn gebouwd in Angular, met Ionic voor de mobiele app.
De backend is gebouwd in Ruby on Rails.