Help development

Translations

If you want to help us fine tune our translations you can do that at https://translate.jodli.dev/projects/esmira/. If you want to translate ESMira into a new language, you are very welcome to. Please contact us via the discussion forum, and we will unlock your language right away!

Developing ESMira

The ESMira project is split into two different parts: Its smartphone apps (Android and iOS) and the server.

Smartphone apps

The smartphone apps can be divided into three parts:

• The native Android app, written in Kotlin, which mainly comprises the UI.
• The native iOS app, written in SwiftUI, which mainly comprises the UI.
• A sharedCode library created with Kotlin Multiplatform Mobile (https://kotlinlang.org/lp/mobile/) that is included in both the Android and iOS app and contains the main codebase.

Prerequisites

• Android Studio, for developing the Android app and compiling the sharedCode library for Android and iOS.
• Kotlin Multiplatform Mobile Plugin for Android Studio (only for the iOS app).
• Xcode for developing the iOS app.

Note: Apple made sure that it is extremely difficult to develop iOS apps on any other operating system than a Mac. If you use Windows or Linux, you will only be able to test the Android app and sharedCode but not the iOS app.

Getting started

1. Download and install Android Studio from https://developer.android.com/studio (you also need it, if you only want to test the iOS app).

2. (Only needed for iOS) Start Android Studio. In the welcome screen select Configure>Plugins. Then select the Marketplace tab, type "Kotlin Multiplatform Mobile" into the search field and install the plugin.

3. (Only needed for iOS) Install Xcode from the App store of your Mac.

4. Clone the project from https://github.com/KL-Psychological-Methodology/ESMira-apps

5. For Android: Open the project that is located in ESMira-apps/androidApp.

6. For iOS: Open the project that is located in ESMira-apps/iosApp.

Structure

In the ESMira-apps folder there are three sub folders:

• androidApp: This is the Android app. Open this folder with Android Studio. It mainly includes code for the UI.
• iosApp: This the iOS app. Open this folder with Xcode. It mainly includes code for the UI.
• sharedCode: This is a shared library which is used in both the Android and iOS app. Most logic and the heavy lifting are done by this library.

Making changes to the sharedCode library

If you are not doing purely decorative changes, you will most likely have to make changes to the sharedCode which is used by both Android and iOS. The sharedCode library is compiled via gradle and included into the Android project which means it is easiest if you open the Android app with Android Studio.

The sharedCode has three sub-modules:

• commonMain: This is where most of the magic happens. You also find a file called common.kt. Some functions or classes are used in commonMain but need to be implemented differently on iOS and Android. These are marked with an expect modifier. Their actual implementation can be found in androidMain and iosMain (more information).
• androidMain: The actual implementation of expect functions / classes for Android (more information).
• iosMain: The actual implementation of expect functions / classes for iOS (more information).

Note: Android Studio has problems showing all modules of multiplatform projects correctly. The folder "androidMain" is not listed for the module "sharedCode" in the "Android" view of the left pane. Use the "Project" view instead.

The server

The server consists of:

• A frontend, which mainly uses native JavaScript (with the help of Knockout.js) and is bundled by (webpack [https://webpack.js.org/]) a npm plugin.
• A backend that uses php.

ESMira does not use an external database. All data is saved into a folder called data and can be found in the dist folder.

Prerequisites

• NodeJs, which comes with npm and is used to build the project.
• A webserver with PHP for testing (e.g. XAMPP on Windows).

Getting started

1. Download and install NodeJs from https://nodejs.org/en/.

2. Clone the project from https://github.com/KL-Psychological-Methodology/ESMira-web

3. Open a console in the folder ESMira-web and run npm install to download its dependencies. This might take a while, depending on your internet connection.

4. Run npm run dev. This will build everything into the dist folder. The process will keep running and will automatically rebuild the project as soon as something changes in the src folder.

Note: If you want to build for production, run npm run prod instead.

5. In your browser, test your ESMira instance by entering the url http://localhost/[PATH-TO]/ESMira-web/dist/ (depending on your server setup).

Structure

The ESMira-web folder has the following sub-folders:

• build_configs: All configurations for the build process are in there.
• dist: This is where the web application will be built to. Do not make changes in here as they will be automatically overwritten.
• src: The actual source files. The files in here will be built by running npm run dev. Changes have to be done in this folder.

Good to know

Developer mode

You can enable the developer mode in the ESMira app to get access to some additional features. To enable it, tap the gear icon at the top right of the starting screen. Then select "About ESMira". In the following screen tap the ESMira icon 10 times until a dialog shows up that asks for a password. There, you enter "Jaynestown" and press OK.

To disable developer mode, press the ESMira icon 10 times again.

This will change the transmitted app_type to XXX_dev (or, if disabled again, XXX_wasDev).