App customisation, extensions, and further development

Totara Mobile has two levels of customisation:

• Customising the look and feel
• Extending the app (requires setting up your development environment)

The basic setup can be found on the Getting started with the Totara Mobile app page. The following section continues on from the Getting started page. 

Look and feel customisation in admin panel

In order to brand the Totara Mobile app with minimal changes, use the official theming product documentation as a reference.

Extending the app

After exploring the theming product documentation, in order to extend the mobile app, you may have the following main options to change:

• App unique application ID
• App icons
• Advanced theming using TotaraTheme
• Caching
• Default language strings

Using a unique app ID will ensure you do not overwrite the official Totara Mobile app from your app drawer. In the same way, a unique icon can visually identify your app.

Further Firebase configuration

In order to run your own app and have push notifications, you have to create your own Firebase project and download your own Firebase config files.

The project comes with sample development Firebase files which will provide you with a runnable project from the start. However, it is still required to have your own file credentials so you can have Firebase services working.

Here is a summary of what you should do:

1. Take note of your app's application identifiers.
   • For iOS, check your bundle identifier in your Xcode set up
   • For Android, check your applicationId in android/app/build.gradle
2. Go to your application Firebase project in the Firebase console.
3. Set up your config files.
   • iOS: Google Firebase for iOS
   • Android: Google Firebase for Android
4. Save your set-up files in your machine.

Android has different a location to place service keys depending on the build type. The key file (google-services.json) should be placed in the following folder locations:

• For the development mode: android/app/src/dev
• For the User Acceptance Testing (UAT) / QA mode: android/app/src/qa
• For the production mode: android/app 

Firebase key file (GoogleService-Info.plist) for the iOS which associated with the build environment (development, QA, or production) should be placed in ios folder. It may be required to replace with the relevant file key when you change it to the different build environment/project configuration.

For more information on the iOS setup, please check the official instruction on Google Firebase for iOS up until you set up the GoogleService-Info.plist file.

For Android, the official instructions are on Google Firebase for Android, so you can get the google-services.json file set up.

Sentry setup (optional)

These instructions are only relevant if your project uses Sentry.

Duplicate .env.example and name it as .env. Set your Sentry variables in .env:


1. SENTRY_AUTH_TOKEN: You can find it here.
2. SENTRY_PROJECT_URL: You can find it here. 

Look and feel 

Below you will find guidance on customising the look and feel of your app, as well as custom digital assets set up. 

iOS

You can modify iOS icons in this folder: ios/TotaraMobileApp/Images.xcassets.

For application ID, open XCode then change the Bundle Identifier to your app ID in the identity section.

Android

You can modify iOS icons in this folder: android/app/src/main/res/.

For Android application ID, change the default Config.applicationid inside android/app/build.gradle.

GraphQL

For any minor changes it would be best to extend the persisted queries as described in the GraphQL documentation, for any changes that are outside the possibilities of the existing schema there are two methods:

• Easier way: Create a lightweight plugin that holds the schema and queries you need, and that implements any custom resolver or formatter classes that you will need
• Safer way: Fork the totara_mobile plugin - this will be a bit of work upfront, but it will allow you much more control in the long term, and if the totara_mobile plugin changes your custom app code will still work

In either case, your queries can alias core GraphQL queries (see /totara/mobile/webapi/mobile/scorm.graphql) or if you need new properties you can implement your own resolvers to extend core (see /totara/mobile/webapi/mobile/course.graphql and the associated resolvers in /totara/mobile/classes/webapi).

TotaraTheme object

TotaraTheme object has the main properties so you can fully customise your app. It can be found in this path: src/totara/theme/Theme.ts

Caching

In order to extend caching, you may check the caching features of the Apollo Client. Please note that by default, Apollo Client's fetch policy is cache-first.

Default language strings

You should be able to customise your language strings in the Totara Mobile plugin. However, some default language strings are predefined because you will need to show some screens before the user connects to the server. You can find default language strings files in this path: src/totara/locale/languages.