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)