overrides

Override assets and configuration

"ode-plugin" CLI tool is provided to customize your application by overriding assets and configuration files. Customization have to be done during the build process. Following elements could be overriden:

• BundleID and App Name
  • Android: android/gradle.properties [APPID,APPNAME]
  • iOS: Info.plist [APPID,APPNAME]
• Launcher Icon
  • Android: override the following files android/src/main/res/*/ic_launcher
  • iOS: override the following files ios/mobileapp/Images.xcassets/AppIcon.appiconset/*
• Launcher Image
  • Android: override the following files android/src/main/res/drawable/*
  • iOS: override the following files ios/mobileapp/Images.xcassets/LaunchImage.launchimage/*
• Assets
  • override image at assets/images/*
  • override icons at assets/icons/*
  • any other assets at assets/*

Configuration

General properties

To configure the plugin just add an "ode" bloc in package.json as follow:

"ode": {
    "appid": "com.ode.appe",//default bundle id
    "appname": "app-e-dev",//default bundle name
    "properties": {//which file need to be update when bundle id/name is overriden
      "ios": "ios/mobileapp/Info.plist",
      "android": "android/gradle.properties"
    },
    "overrides": [//list of folders that could be overriden
      "assets/*",
      "android/app/src/main/res/*",
      "mobileapp/Images.xcassets/*"
    ],
    "config": {
      ...//see belows how it works
    }
  }

Environement's configuration

Config files are not tracked by GIT (they are ignored). They also could change according to the environnement (ie. production, integration). Below some examples of confidential config files:

• Platform Config File: override app/Conf.ts
• Firebase config files:
  • Android: android/app/config.json
  • iOS: ios/mobileapp/config.plist

Config files are defined in package.json as follow:

"ode": {
   ...
    "config": {
      "id": "neo-recette", //default config applied
      "url": "http://test.git  ", //(optionnal) default git repository where the CLI will fetch configs
      //mappings between config files in repository and the current project
      "config.android.json": "android/app/config.json",
      "config.ios.plist": "ios/mobileapp/config.plist",
      "Conf.ts": "app/Conf.ts"
    }
  }

Config files MUST be ignored by applcation git repository

Config repository layout

Config are stored in secured git repository. The folder structure should be as follow:

my_env1
  config_file1
  config_file2
  config_file3
my_env2
  config_file1
  config_file2
  config_file3
...

The folder is used by the CLI as config.id. So in your package.json when you have

"ode": {
   ...
    "config": {
      "id": "my_env1",//default config applied
    }
  }

It will load config from my_env1 folder.

Then you define in your package.json a mapping between config files and project files as follow:

"ode": {
   ...
    "config": {
      ...
      //mappings between config files in repository and the current project
      "config_file1": "android/myfile",
      "config_file2": "ios/myfile",
      "config_file3": "app/myfile"
    }
  }

Commands and options

override

$ node ode-plugin.js override --help
ode-plugin.js override

manage overrides

Commandes:
  ode-plugin.js override switch   switch to an override
  ode-plugin.js override restore  restore the default override
  ode-plugin.js override backup   backup the current override
  ode-plugin.js override create   create a new override

Options:
  --help     Affiche de l'aide                                         [booléen]
  --version  Affiche le numéro de version                              [booléen]
[rafik@localhost mobile-app]$ node ode-plugin.js override switch --help

To see which override is currently apply, use the command below:

$ node ode-plugin.js override
There are no overrides applied!

override create

$ node ode-plugin.js override create --help
ode-plugin.js override create

create a new override

Options:
  --help     Affiche de l''aide                                         [booléen]
  --version  Affiche le numéro de version                              [booléen]

Follow instructions and enter

• the name of the override (to identify it)
• the application's Id (or bundle id use to identify the app in stores). Genrally a fully qualified name.
• the application's name: the display name of the app in stores
• the config's ID: we will see below how to define config

And finally the prompt suggest to switch to the new override. When switching to an override, all assets updates should not be tracked by git.

override switch

$ node ode-plugin.js override switch --help
ode-plugin.js override switch

switch to an override

Options:
  --help           Affiche de l''aide                                   [booléen]
  --version        Affiche le numéro de version                        [booléen]
  --to             name of the override to switch to (if you set ''default'' it
                   will only fetch config)                              [requis]
  --dontrestore    if setted the restauration does not occurs
  --uri, -h        uri of the git repo (uri could include password and username)
  --username, -u   username of the git repo
  --password, -p   password of the git repo
  --acceptall, -a  accept all prompts

When you switch to a new override, you apply all changes defined in the override:

• override assets (react, android, ios)
• override app id and app name (android, ios, package.json)
• optionnally you can load the config associated to the override (maybe your overriden app have a different firebase config file?)

To switch to an override just type and follow prompted instrcutions

$ node ode-plugin.js override switch --to=test

Under the hood, the CLI first restore your project before applying override changes. Before making any changes, the CLI check all files that are going to be replaced and aks whether it should make replacement. When it has finished to apply override, it asks if it should also fetch the config associated to the override.

override backup

$ node ode-plugin.js override backup --help
ode-plugin.js override backup

backup the current override

Options:
  --help     Affiche de l''aide                                         [booléen]
  --version  Affiche le numéro de version                              [booléen]

If you have overriden some assets, you can save save changes for this override using the following command:

$ node ode-plugin.js override backup

The CLI will check (using git) all changed files and will ask if it should backup them. It will also detect any overriden files that has been reverted and suggest to remove it from backup. And finally the plugin ask whether you would like to reset override.

All overriden assets will be backed up the override folder at the root of the project.

override restore

node ode-plugin.js override restore --help
ode-plugin.js override restore

restore the default override

Options:
  --help     Affiche de l''aide                                         [booléen]
  --version  Affiche le numéro de version                              [booléen]

To restore an override use the command below:

$ node ode-plugin.js override restore

The plugin will list all overriden assets that need to be restored and will ask whether it should reset files.Then it will reset app ids and bundle name (ios,android, package.json). And finally it will ask whether he should restore the default config (defined in package.json).

fetch-config

$ node ode-plugin.js fetch-config --help
ode-plugin.js fetch-config

get config from git

Options:
  --help          Affiche de l''aide                                    [booléen]
  --version       Affiche le numéro de version                         [booléen]
  --uri, -h       uri of the git repo (uri could include password and username)
  --username, -u  username of the git repo
  --password, -p  password of the git repo

You can load configuration files from a git repository using the command below;

$ node ode-plugin.js fetch-config

The plugin will automatically load the config attach to your current override (or your default config if no override is applied).