doc: Add ios specific documentation, format text

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
 
 ![How to install Android CLI tools](./document/images/android_sdk_cli_tools.png "How to install Android CLI tools")
 
-
-
 ### 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.
 
 ![Signing an app in XCode](./document/images/ios_signing.png "Signing an app in XCode")
 
 ### Distributing
+
 In XCode, click `Product -> Archive`, and then select the latest build and Distribute. Click all sorts of yesses and hope for the best.
 
 ![Archive](./document/images/Xcode-archive.png "Archive")
@@ -263,7 +284,8 @@ In XCode, click `Product -> Archive`, and then select the latest build and Distr
 ![Success](./document/images/Xcode-distribute-success.png "When everything goes according to plan")
 
 ### 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.
 
 ![TestFlight](./document/images/testflight.png "TestFlight")
 
@@ -272,6 +294,7 @@ However, you can update the **build** in TestFlight without changing the common
 ![XCode build version](./document/images/Xcode-build-versjon.png "XCode build version")
 
 ### 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)