diff --git a/README.md b/README.md index 306f70945fd01e476e16306dbf9f07ade8962dc3..53896fbf6d0f2f4bf62b95c0178400b51e7d7ee0 100644 --- a/README.md +++ b/README.md @@ -5,37 +5,43 @@ Providing an easy way to register pest observations made in the field by registered VIPS users. Available for Android and iOS smartphones. ## Architecture -The app has been built using -* [Apache Cordova](https://cordova.apache.org/) v.11.0.0 -* [Vue.js version 2](https://v2.vuejs.org/) and [vue-cli](https://cli.vuejs.org/) + +The app has been built using + +- [Apache Cordova](https://cordova.apache.org/) v.12.0.0 +- [Vue.js version 2](https://v2.vuejs.org/) and [vue-cli](https://cli.vuejs.org/) Most of the UI has been built in vue, and then compiled to the cordova www folder, and then subsequently used to build for the smartphone platforms. ## Prerequisites: node, npm, vue-cli and cordova + Make sure you have the correct versions of npm and nodejs Use nvm to install, here's [how to install nvm in the first place](https://github.com/nvm-sh/nvm#installing-and-updating) Then run: -``` bash +```bash nvm install --lts sudo npm install -g @vue/cli --unsafe-perm -sudo npm install -g cordova --unsafe-perm -``` +sudo npm install -g cordova@12.0.0 --unsafe-perm +``` ## Build Setup (vuejs) + You need to add your local configuration file before you do this. The file's name must be `src/components/CommonUtilLocal.vue`, and here's example content: + ```html <script> - export default { - CONST_URL_DOMAIN : 'https://logic.vips.nibio.no', - CONST_DEBUG : false - } + export default { + CONST_URL_DOMAIN: "https://logic.vips.nibio.no", + CONST_DEBUG: false, + }; </script> ``` + Then you can install the dependencies and run the test web server -``` bash +```bash # install dependencies npm install @@ -53,25 +59,30 @@ For a detailed explanation on how things work, check out the [guide](http://vuej ## Build/emulate with cordova -``` bash -# Add browser and android platforms (haven't tested iOS yet) +```bash +# Add browser, android and ios platforms cordova platform add browser cordova platform add android +cordova platform add ios # Test in browser cordova emulate browser -# Test on Android. Requires correct setup of the Android SDK. +# Test on Android. Requires correct setup of the Android SDK. # Read more here: https://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html cordova emulate android +# Test on IOS. Install Xcode from Mac AppStore, and the iOS Simulator +cordova emulate ios ``` ### Troubleshooting Android platform builds -* If you upgrade cordova or change the package name of the app (in config.xml), -you should reset the platform, using `cordova platform remove android` and then `cordova platform add android` + +- If you upgrade cordova or change the package name of the app (in config.xml), + you should reset the platform, using `cordova platform remove android` and then `cordova platform add android` #### Error message when starting the Android emulator + (When running `cordova emulate android`) ``` @@ -83,9 +94,8 @@ This can be solved by installing the Android command-line tools, as [per these i  - - ### Connecting to a local server + While developing, you will want to connect to a local instance of VIPSLogic. This is done by editing the property `CONST_URL_DOMAIN` in `/src/components/CommonUtilLocal.vue`. Set it to whatever domain name you wish (e.g. vipslogic-local.no) and then edit your `/etc/hosts` file to point this to the IP address 10.0.2.2, like this ``` @@ -94,26 +104,28 @@ While developing, you will want to connect to a local instance of VIPSLogic. Thi ## Test on an Android phone -After running `npm run build`, you can find the Android package (`.apk`) in `/platforms/android/app/build/outputs/apk`. -By connecting your Android phone to your computer and copying the file to your phone, you can install it on the phone. **This -depends on you having enabled developer mode on your phone**. How to do that differs a great deal, so search the interwebs for +After running `npm run build`, you can find the Android package (`.apk`) in `/platforms/android/app/build/outputs/apk`. +By connecting your Android phone to your computer and copying the file to your phone, you can install it on the phone. **This +depends on you having enabled developer mode on your phone**. How to do that differs a great deal, so search the interwebs for how to do it. - - ## Develop the code + ### Don't touch the /www folder! -Normally in Cordova you would put your code here, but this is where vue-cli is putting the things that it builds. + +Normally in Cordova you would put your code here, but this is where vue-cli is putting the things that it builds. ### Where to update app version -* `/package.json` (Updates version in the Settings/About section in the app) -* `/config.xml` + +- `/package.json` (Updates version in the Settings/About section in the app) +- `/config.xml` ### Main template + The main layout is based on a very simple template snatched from Bootstrap. You find it in /html (at the project root level). Everything that Vuejs operates on happens inside the `main` element -``` html +```html <main id="app" role="main" class="container"></main> ``` @@ -124,18 +136,19 @@ Looking at /src/main.js, the Vue app is not started until Cordova fires the devi The router components (the "pages" in the Single Page Application that you manage) are found in `/src/components`. The router (paths + components definitions) is found in `/src/router/index.js` ### Checking out new code + Remember to always run `npm install` after checking out new code from the repository. That way, new dependencies will be installed. ### Translation + [This tutorial](https://www.codeandweb.com/babeledit/tutorials/how-to-translate-your-vue-app-with-vue-i18n) has been used to enable translation. I couldn't get the per-component translation thing working (where you embed it in `<i18n>` tags), so all translations go into the `/locales/[languagecode].json` files. - There's a simple translation example in `/src/components/PlacesList.vue`: -``` html +```html <template> <div> <!-- ... --> @@ -151,21 +164,26 @@ There's a simple translation example in `/src/components/PlacesList.vue`: Change the startup language in the app here in `/i18n.js`: -``` javascript +```javascript export default new VueI18n({ - locale: process.env.VUE_APP_I18N_LOCALE || 'nb', // Here you can customize - fallbackLocale: process.env.VUE_APP_I18N_FALLBACK_LOCALE || 'en', - messages: loadLocaleMessages() -}) + locale: process.env.VUE_APP_I18N_LOCALE || "nb", // Here you can customize + fallbackLocale: process.env.VUE_APP_I18N_FALLBACK_LOCALE || "en", + messages: loadLocaleMessages(), +}); ``` + To translate in JavaScript, refer as `this.$i18n.t`, e.g.: -``` javascript -lstPOI.push({pointOfInterestId:'undefined',name: this.$i18n.t("mapobservation.label.noPOIselected")}); +```javascript +lstPOI.push({ + pointOfInterestId: "undefined", + name: this.$i18n.t("mapobservation.label.noPOIselected"), +}); ``` -### Adding Internationalization -``` bash +### Adding Internationalization + +```bash npm install vue-i18n --save ``` @@ -188,6 +206,7 @@ emulator -avd Pixel_3a_API_30_x86 -wipe-data Replace your emulator name with the example above ## Android publishing + Before building, signing and publishing, make sure you bump the version in `package.json` ```json @@ -204,6 +223,7 @@ Before building, signing and publishing, make sure you bump the version in `pack "start": "npm run dev" }, ``` + ...and in config.xml ```xml @@ -218,20 +238,21 @@ Before building, signing and publishing, make sure you bump the version in `pack For NIBIO, a signing key was originally created sometime in 2021, but it has been lost. After contacting Google Play Developer Support, we received instructions for how to generate a new key (example code): -``` bash +```bash keytool -genkeypair -alias upload -keyalg RSA -keysize 2048 -validity 9125 -keystore keystore.jks ``` -...so we did this, and stored the keystore *securely* (in a dev project folder) +...so we did this, and stored the keystore _securely_ (in a dev project folder) We then extracted the PEM to send to Google (example code) -``` bash +```bash keytool -export -rfc -alias upload -file upload_certificate.pem -keystore keystore.jks ``` Signing can be done like this (example): -``` bash + +```bash $ cordova run android --release -- --keystore=[PATH_TO_KEYSTORE] --storePassword=[KEYSTORE_PASSWORD] --alias=upload --password=[PASSWORD] --packageType=bundle ``` @@ -248,14 +269,14 @@ https://developer.android.com/guide/app-bundle https://developer.android.com/studio/publish#unknown-sources - - ## iOS Publishing + On iOS, do the regular `npm run build`, and then `cordova build ios`. You should then be ready to run the app in a simulator or a real device in XCode. Remember that in order to run it on a real device, you must sign it (see XCode screenshot below) with either your personal team account (for debug only) or a company account for distributing to App Store.  ### Distributing + In XCode, click `Product -> Archive`, and then select the latest build and Distribute. Click all sorts of yesses and hope for the best.  @@ -263,7 +284,8 @@ In XCode, click `Product -> Archive`, and then select the latest build and Distr  ### Versioning -You set the main version in `/config.xml` and `package.json` (in the source code, before building for iOS) - that's what's going to show in TestFlight/App store. + +You set the main version in `/config.xml` and `package.json` (in the source code, before building for iOS) - that's what's going to show in TestFlight/App store.  @@ -272,6 +294,7 @@ However, you can update the **build** in TestFlight without changing the common  ### Enabling developer mode + #### iOS 16 -[This is how you do it](https://developer.apple.com/documentation/xcode/enabling-developer-mode-on-a-device) +[This is how you do it](https://developer.apple.com/documentation/xcode/enabling-developer-mode-on-a-device)