mendix-hybrid-app-custom

Mendix hybrid app custom extension package for PhoneGap / Cordova

This repository contains the extension files needed to build a Phonegap package for a Mendix application that has custom functionality. This custom functionality is not currently supported by the default Mendix application. Please do read the build instructions carefully as the solution to block the backbutton requires changes at multiple levels to get it working properly. This guide is written with Mendix developers in mind who do not have much experience at low level customization.

Functionality that this module brings (This may be extended in the future when needed):

• Android backbutton can be disabled when the app loses its data connection.
• Android backbutton can be disabled permanently

Limitations that come with this module

• Current coding is for hybrid-mobile-apps that do NOT use a Pincode to access the application. It is possible to extend the code for pincode enabled Mendix applications.
• As it changes the Mendix phonegap package, this adaptation has to be implemented every time a new phonegap build is needed. Particularly when upgrading to a newer version of Mendix.

Prerequisites

• A Mendix account
• A Mendix hybrid application using the mobile_features widget from the Mendix app store.
• Node.js
• npm
• phonegap
• webpack

Build (Windows 10)

There are quite a few steps involved to get everything working, so please follow the instructions carefully. The hard part of doing the research, coding and debugging has been done, so enjoy! :-)

Add the mendix-hybrid-app-custom module to your project

• Commit any changes in your Mendix desktop modeler project before proceeding.
• Login to the Mendix website and proceed to your app on the website.
• Proceed to the deploy section of your app, select mobile-app and press the button on the right with the caption 'publish for mobile app store'
• Choose to build the package yourself and download the phonegap zip package to a folder on your harddrive. Do not extract it on your desktop as that will fail the phonegap installation process.
• Extract the zip file and navigate to the newly created folder.
• Open package.json
• Under "dependencies", replace "mendix-hybrid-app-base" with "mendix-hybrid-app-custom" and set the version to 1.0.18 or the latest that is currently available on npm.
• Save and exit package.json
• Open the command promp (Windows button + R, "cmd", enter) and navigate to the folder created at the beginning.
• If not done yet, install node.js and npm. (Google search: install npm on windows 10) Do these installations on the windows command prompt, not git bash or other similar programs.
• Verify the install was completed correctly.
• Install the latest phonegap version. (example: "npm install -g phonegap@7.1.0")
• Execute: "npm install" from within the new folder.

Include blockbackbutton.js in your Mendix project.

• Navigate to ./node_modules/mendix-hybrid-app-custom/src/www/ and copy blockbackbutton.js.
• Navigate to your main mendix project folder, proceed to ./theme/js/ and paste blockbackbutton.js here. Create the js folder if necessary.
• Navigate up one folder and open components.json.
• Inside the "js" array, add "js/blockbackbutton.js".

"js":["mxclientsystem/mxui/mxui.js", "js/blockbackbutton.js"]

• Save and exit components.json
• Make sure your Mendix project is up to date with the main line as this is the branch that gets published by Mendix.
• The project can now be run and/or committed with these changes to the Mendix cloud repository. The proper phonegap package still has to be created however.

Adapt mendix-hybrid-app-base (Tested with Mendix version 7.16.0)

• Navigate from the extracted main folder created at the beginning to ./node_modules/mendix-hybrid-app-base/src/www/scripts/ and open app.js
• Disable line 720 by commenting it out with '//'s in front.

// document.addEventListener("backbutton", handleBackButton);

• Disable the code in the replaceEventHandler function by commenting out both lines inside:

// if (oldHandler) document.removeEventListener(eventType, oldHandler);
// if (newHandler) document.addEventListener(eventType, newHandler);

• Save and exit app.js

Create the phonegap package and application.

• In the terminal, navigate to the extracted main folder created at the beginning.
• Install webpack: "npm install --save-dev webpack".
• Execute: "npm run package"
• Navigate to ./dist and find the phonegap zip file. (There will be two: It is the newest folder)
• Upload the zip file to the phonegap build website.
• Enable debugging (if you think you need it) and confirm that the app is ready to build.
• Download the apk or scan the QR code at the phonegap build website when building has been completed using a general QR scanner on your android device
• Install the app
• Make sure that the application has been started in the Mendix modeler.
• Start the app
• Navigate in the app to a page that has a mobile_features widget.
• Test that the backbutton is blocked when flight mode is activated.

OPTIONAL: Disable the backbutton permanently.

• Open blockbackbutton.js.
• Comment out line 1:

"// setInterval(function() { handleOnlineOfflineStatus(); }, 500);".

• Remove the "//"'s at line 3:

"disableBackButton();".

• Save and exit blockbackbutton.js.
• Run the project and if not done yet, create the phonegap package and application from step 14.

Terminal commands overview

$ npm install -g phonegap@7.1.0	    # Install phonegap
$ npm install --save-dev webpack    # Install webpack
$ npm install                       # Install dependencies
$ npm run package		    # Create the Phonegap archive that can be uploaded to Phonegap build

Enjoy!

Kudos to my company Vitatech who gave me the time to research this solution. Feel free to contact me with questions and suggestions!