Adapt your plugins to Ionic 5: Difference between revisions

Revision as of 10:43, 6 April 2021

This template is unused and can be deleted.

Introduction

These past few months we've been working on updating the Ionic framework in the mobile app to Ionic 5. As usual, we tried not to change our APIs and components to prevent breaking existing plugins. Unfortunately, Ionic 5 comes with a lot of breaking changes, especially related to templates. This means that your plugins will need to be adapted in order to look good in the version 3.9.5 of the app.

We're still in the process of migrating some features and fixing things, but we've reached a point where we have a stable app that you can use to test your plugins. We've published this webapp so you can test them:

Ionic 5 WebApp

If you prefer to test this in a local environment you can use the ionic5 branch in our repository:

App source code

When will the app with Ionic 5 be published?

We’re planning to publish the app at the end of June. This means you have about 2 months to adapt your plugin.

My plugin doesn’t use Ionic components or Javascript, do I need to adapt it?

In that case it’s possible that you don’t need to adapt the plugin to make it work. We recommend you to test the plugin in the Ionic 5 app to check if everything works.

Supporting both Ionic 3 and Ionic 5

Your plugin should still support Ionic 3 so it works in devices that haven’t updated the app yet. This can easily be done by checking the value of appversioncode sent by the app. I uploaded an example applied to the choicegroup plugin:

Choicegroup code

As you’ll see, I duplicated the JS and the templates so I have a file to support Ionic 3 and a file to support Ionic 5. I decided to name them “ionic3” and “latest”, but you can structure this as you prefer. You can also have a single file with different HTML depending on the appversioncode, that’s up to you.

Ionic changes

As commented before, Ionic has changed a lot of their components, directives and utilities.

In the following 2 pages you’ll find most of the changes done by Ionic and how do you need to change your code to make it work in Ionic 5:

https://github.com/ionic-team/ionic-framework/blob/master/BREAKING.md#version-5x

https://github.com/ionic-team/ionic-framework/blob/master/angular/BREAKING.md

Besides the changes in templates, it’s important to notice that all functions related to modals are now asynchronous. This means that if your plugin is displaying a modal in Javascript then you’ll probably need to adapt your code too.

Another important thing to notice is that the text inside an <ion-item> now should always be inside an <ion-label>, otherwise it might not look good in some cases. E.g.:

<ion-item>My text</ion-item>

Should now be:

<ion-item><ion-label>My text</ion-label></ion-item>

Finally, another important change is that now all Ionic tags are components, e.g. <ion-label> or <ion-avatar>. This means that these tags cannot have another component in them. Some common cases that will need to be modified:

<ion-label core-mark-required=”true> now needs to be: <ion-label>

<ion-avatar core-user-avatar …> now needs to be: <core-user-avatar …>

You can now use ES6

In v3.9.5 we will increase the minimum Android version to use the app. The newer Cordova and Ionic versions only support Android 5.1+ with newer WebViews, so that will also be the requirement of the app.

The new app will require Android 5.1 with WebView 61+. This means that the Javascript for the app can now be developed in ES6 instead of ES5. Also, you can use arrow functions since they were introduced in WebView 55 and iOS 10.3.

This means that the app is no longer transpiled to ES5, and that can break your plugin’s Javascript if you’re extending a class. In Ionic 3, when your plugin receives a class it actually receives a function, and that affects the way to extend it. Now your plugin will receive a Javascript class.

E.g. to create a subclass of CoreContentLinksModuleIndexHandler you had to do:

function AddonModCertificateModuleLinkHandler() {

   that.CoreContentLinksModuleIndexHandler.call(this, that.CoreCourseHelperProvider, 'mmaModCertificate', 'certificate');

   // Rest of constructor.

AddonModCertificateModuleLinkHandler.prototype = Object.create(this.CoreContentLinksModuleIndexHandler.prototype); AddonModCertificateModuleLinkHandler.prototype.constructor = AddonModCertificateModuleLinkHandler;

Now it’s done like this:

class AddonModChoiceGroupLinkHandler extends this.CoreContentLinksModuleIndexHandler {

   constructor() {
       super('AddonModChoiceGroup', 'choicegroup');

       // Rest of constructor.
   }

}

Changes in the app’s code

We’ve also done some changes to the code of the app. Most of these changes probably won’t affect your plugin, but we still list them all just in case:

<core-icon> is now deprecated, please use <ion-icon> instead. Right now you can use font-awesome icons with ion-icon. However, it still hasn’t been decided whether font awesome will be used in Moodle 4.0 or not, so it might happen that font-awesome is removed from the app in the future.
To “cross out” an icon using ion-icon now you need to use class=”icon-slash” instead of slash=”true”.
The function syncOnSites from CoreSyncBaseProvider now expects to receive a function with the parameters already bound. That is, instead of:

syncOnSites(‘events', this.syncAllEventsFunc.bind(this), [force], siteId);

You should now do:

syncOnSites(‘events', this.syncAllEventsFunc.bind(this, force), siteId);

All the delegates that previously supplied an injector parameter to its handlers now no longer do that. E.g. the function getComponent() in CoreUserProfileFieldDelegate used to receive an injector as a parameter, now it won’t receive any parameter.
All the delegates that previously supplied a NavController parameter to its handlers now no longer do that. E.g. the function openCourse() in CoreCourseFormatDelegate will no longer receive the NavController parameter.
The handlers registered in CoreCourseOptionsDelegate now need to return the properties page+pageParams instead of component+componentData. Please notice this only affects you if you’re creating the handler yourself using Javascript code.
The handlers registered in CoreUserDelegate have changed a bit. Please notice this only affects you if you’re creating the handler yourself using Javascript code.
- Handlers can now define a cacheEnabled property (false by default) to cache isEnabledForUser calls.
- In the function isEnabledForUser, the params navOptions and admOptions have been removed.
- isEnabledForUser is now optional and defaults to true.
- Now they can implement a new function isEnabledForCourse, and this function will receive the navOptions and admOptions. If not defined defaults to true.
The function prefetchPackage in the CoreCourseActivityPrefetchHandlerBase has changed. If you were using this class to implement your own prefetch handler you might need to update its code.
CoreInitDelegate has been deleted. Now the initialization of the app is done via Angular’s APP_INITIALIZER. Please notice that APP_INITIALIZER cannot and shouldn’t be used by plugins.
The function getAdditionalDownloadableFiles in question types now needs to return a list of CoreWSExternalFile, it no longer accepts a list of strings.
Files stored to be uploaded later using CoreFileUploaderProvider no longer have an “offline” property, now they’re just instances of FileEntry.
ionViewCanLeave function has been renamed to canLeave.
The onchange method of the Network service is now called onChange.

Is there any example I can look at?

If you used the app’s code as an example to build your plugin you can do it again. Most of the templates in the app have already been adapted to Ionic 5. You can see the Ionic 5 code in this branch: