Mendix apps can simply be viewed in mobile web browsers. However, some features of mobile devices cannot be accessed through HTML and JavaScript. Also, if you want to publish your app in the Apple App Store or Google Play Store, you have to wrap your app in a native shell. We use Cordova/PhoneGap to do this. PhoneGap creates a native wrapper around a web application and provides access to native functionality through a JavaScript API. These apps are called hybrid apps because they are a hybrid of a web and a native app.
This project contains the Mendix PhoneGap Build app template. You can use it to
- customize your mobile Mendix app: styling, icons, splash screens and code,
- open the platform specific code inside the appropriate IDEs,
- debug the app using emulators,
- build installable packages, either locally or in the cloud using PhoneGap Build.
- Prerequisites
- Build on PhoneGap
- Customize DTAP endpoint
- App signing
- Build and run locally
- Customizing your app
- Troubleshooting
Make sure that the following is installed on your system:
- A clone of this repository or the customizable package for your app, available in the 'Deploy' section of the Mendix Portal. When starting from a customizable package, basic configuration for your app has already been done.
- Recent
Node.js. This code was tested with version 6. You can check by runningnode -v.- Windows: install from nodejs.org
- MacOS: use Brew to install
Node.js:brew install node - Linux, BSD, etc: install using the available package manager, e.g. on Debian:
sudo apt-get install node
For building locally you also need a development environment for your target platform:
- Android
- Android Studio by following the instructions
- iOS (only available for Apple computers, e.g. MacBook, iMac)
With the PhoneGap Build service you can build your app in the cloud, even if you haven't installed the development environment for your target platform. This way you can target iOS without owning an Apple computer. You still need an Apple developer account, provisioning profile and signing key. See the PhoneGap site for more details.
To use the PhoneGap Build service you need to register for an account
first. After that, you can build your app by uploading a PhoneGap Build package, which is just a
regular .zip file containing JavaScript and resource files.
PhoneGap build packages target either ARM (phones and most other devices) which is the default, or x86 platforms (emulators and other devices).
To build through the PhoneGap site, first build a PhoneGap Build package:
$ npm install # install dependencies
$ npm run package # create ARM PGB package in `dist` or
$ npm run package:x86 # create x86 PGB package in `dist`
Then, go to https://build.phonegap.com/apps/ and click the
+ new app button. When asked, upload the PhoneGap Build package from the dist folder.
To build on PhoneGap Build through the command line:
$ npm install # install dependencies
$ npm run package # prepare `build` directory for ARM or
$ npm run package:x86 # prepare `build` directory for x86
$ npm run phonegap:login # login into the PGB service
$ npm run phonegap:build:android # build on PGB, alternatively use `phonegap:build:ios`
To target a specific DTAP endpoint with your app you can specify it as a parameter to
npm run package or npm run package:x86, e.g:
$ npm run package -- --env.target=test # target the test endpoint for ARM architecture
Possible targets are development, test, acceptance, production (default) and sandbox. For
convencience you can shorten these to the first letter.
In case you want to deploy your app on a real device, you will likely need to sign your app. Please refer to the appropriate Cordova documentation for details:
If this is the initial build, first do some preparation:
$ npm install # install dependencies
$ npm run package:x86 # prepare `build` directory for x86, or
$ npm run package # prepare `build` directory for ARM
$ npm run platform:all # setup for Android and iOS, or
$ npm run platform:android # setup for Android, or
$ npm run platform:ios # setup for iOS
If you cloned the repository or want to change some settings, edit the file config/parameters.json
(create it if necessary). It should at least contain the following properties, with values
appropriate for your app:
{
"identifier": "io.mxapps.myapp",
"name": "My App",
"url": "https://myapp.mxapps.io"
}For information on further customization, refer to Customizing your app.
Now, build and run the app:
$ npm run package:x86 # prepare `build` directory for x86, or
$ npm run package # prepare `build` directory for ARM
$ npm run prepare:all # prepare phonegap platform files
$ npm run start:emulator # run on emulator, alternatively use start:device
When you first download this project, it is mostly empty. All functionality and styling is by
default implemented as part of one this project's dependencies, called mendix-hybrid-app-base.
You can customize your hybrid app in several ways. All defaults from the base package can be overridden and/or extended, including the build process itself.
The project structure consists of the following elements:
src/: this is where you place all customizations for your appwww/:images: any images that you'd like to use on e.g. the login screenstyles: CSS files with styling for e.g. the login screenscripts: JavaScript files that customize the behavior of your appindex.html.mustache: Mustache template file used to generate the index page
resources/: icons and splash screensconfig.xml.mustache: template file that is used to generate the Phonegap configuration file
config/: this is where external configuration files go; these files are optional, overriding the defaults. Example files containing the defaults are put here uponnpm install. Possible configuration files are:environments.json: a description of all available deployment environments for your app, including the app IDs and URLsparameters.json: settings that influence some aspects of the build process and the resulting app, such as Android/iOS support, offline mode, and pin loginresources.json: descriptions of all resources, such as icons and splash screens, including their types and sizestexts.json: translations/customizations for the static texts in the hybrid shell part of your app
build/: (generated) contains all intermediate build files, such as the bundles javascript and css. The contents of this folder are overwritten every time you run a builddist/: (generated) the final build packages will end up herewebpack.config.js: starting point for the build process
Several simple app settings, such as the app name and identifier, can be set in
config/parameters.json. If you've downloaded this project from the Mendix Portal, the file is
already there. Otherwise, you can look at the config/parameters.json.example file.
To customize the styling of the login screen (including the pin screen), add a .css file to
src/www/styles/. It will be automatically picked up by the build process.
To change the structure and contents of the login screen (including the pin screen), you can adapt
src/www/index.html.mustache.
All static text in the hybrid app can be customized and/or translated. To do so, create a file
config/texts.json containing the original text as keys and the replacement text as values. You can
take a look at config/texts.json.example to see which texts are available for translation.
Icons and splash screens are configured in two separate places. The image files themselves should be
stored in src/resources/. The configuration of each icon and splash screen should be updated in
config/resources.json. You can take a look at config/resources.json.example for an example.
In case you have downloaded this package through the Mendix Portal, all configured icons and splash screens have already been prepackaged and preconfigured.
You can run custom code in two specific cases:
- on client configuration setup
- on Mendix client load
To implement custom behavior for these cases, edit src/www/scripts/entry.js.
You can customize the build process by making changes to webpack.config.js in the root folder of
this project. All Webpack configuration you add here will be merged with the default Webpack
configuration. You can read more about this in the
webpack-merge documentation.
Default functionality and styling is implemented in the mendix-hybrid-app-base package. We will
occasionally release updates to this package. You can upgrade the base package by running
npm upgrade from the root of your project.
When using the PIN feature while running your app on an iOS simulator, you experience an issue where the
app will prompt you to setup a PIN every time app is launched. This is due to the underlying way Cordova access the Keychain.
Either use a device, or enable Keychain Sharing in Capabilities of your project.
See here for more information.
Please see here for the steps to support iPhone X in your app.
When building your hybrid app locally, the Android build might fail. This can have various reasons, but it generally boils down to version mismatches related to Gradle and/or the Android SDK in use.
Could not find an installed version of Gradle either in Android Studio,
or on your system to install the gradle wrapper. Please include gradle
in your path, or install Android Studio
Either
- open the Android project (located in
build/platforms/android) in Android Studio and accept its suggestion to install the Gradle wrapper; or - make sure that Gradle is available on your path, e.g.
export PATH=$PATH:/Users/MyUser/.gradle/wrapper/dists/gradle-4.4-all/xxx/gradle-4.4/bin.
You can find installation instruction for Gradle on the Gradle website.
In build/platforms/android/build.gradle, replace
classpath 'com.android.tools.build:gradle:3.0.1' with classpath 'com.android.tools.build:gradle:3.1.2'
and perform a Gradle sync.
AGPBI: {"kind":"error","text":"error: resource android:attr/fontVariationSettings not found.","sources":[{"file":"/Users/Kevin/.gradle/caches/transforms-1/files-1.1/support-compat-28.0.0.aar/4abf4d56829ea1da7befcfae3c8fd6c7/res/values/values.xml","position":{"startLine":132,"startColumn":4,"startOffset":7725,"endColumn":69,"endOffset":7790}}],"original":"","tool":"AAPT"}
AGPBI: {"kind":"error","text":"error: resource android:attr/ttcIndex not found.","sources":[{"file":"/Users/Kevin/.gradle/caches/transforms-1/files-1.1/support-compat-28.0.0.aar/4abf4d56829ea1da7befcfae3c8fd6c7/res/values/values.xml","position":{"startLine":132,"startColumn":4,"startOffset":7725,"endColumn":69,"endOffset":7790}}],"original":"","tool":"AAPT"}
In build/platforms/android/project.properties, replace
target=android-27 with target=android-28
and perform a Gradle sync.
When building your app locally, you should add the platforms of your choosing by running:
$ npm run platform:all # setup for Android and iOS, or
$ npm run platform:android # setup for Android, or
$ npm run platform:ios # setup for iOS
When Android is your only target, you can choose the second option.
Unfortunately, this does not work in the case of iOS, because some plugins require the android platform to be present.
To work around this, you should make sure that the Android platform was added before running npm run package:ios, either by running npm run platform:all, or by running npm run platform:android beforehand.
If required, you can later remove the android platform by running npm run platform -- remove android.
The Push Notifications plugin requires some additional components, which are installed through CocoaPods.
To trigger this installation, we always call pod install as part of the platform and prepare commands.
If you have disabled the push capability, this step is superfluous.
This will show up in your logs as [!] No 'Podfile' found in the project directory.
You can safely ignore this error.