Overriding App Resources¶

From 5.2 or newer version, Mobile Development Kit supports the ability to override only a part of resources files in <generated-project>/app/App_Resources. This is done by specifying your overriding files in the .mdkproject/App_Resources_Merge.

Files in the .mdkproject/App_Resources_Merge folder support merge (replace/add) for the following file types, other files will be overwritten.

The flow of app resources override is as follows:

All the files in .mdkproject/App_Resources will be copied (and overwrite any existing files) to <generated-project>/app/App_Resources folder.
Next, the files in .mdkproject/App_Resources_Merge will be processed and merged to the <generated-project>/app/App_Resources.

Note

The path of the files in App_Resources_Merge folder must match the path of the files you want to override in the App_Resources folder.e.g.

If your target file is in:

/App_Resources/Android/src/main/AndroidManifest.xml

Then your must put your source file in:

/App_Resources_Merge/Android/src/main/AndroidManifest.xml

Supported File Types¶

Merging of resources support the following file types, it will merge them if it finds the same file in the <generated-project>/app/App_Resources folder, otherwise it will copy them over.

Due to the different usage method of each file types, the merging strategy for each files types can be different, as described here:

.plist files (iOS): This type of files will be merged using /usr/libexec/PlistBuddy to merge into the file with the same name / path in <generated-project>/app/App_Resources folder. PlistBuddy is a macOS built-in tool from Apple for editing .plist files.
.xcconfig files (iOS): This type of files will be merged into the file with the same name / path in <generated-project>/app/App_Resources folder. Value of existing keys will be replaced, new keys will be added.
.strings files (iOS): This type of files will be merged into the file with the same name / path in <generated-project>/app/App_Resources folder. Value of existing keys will be replaced, new keys will be added.
.gradle files (Android): This type of files will be merged into the file append the contents to the file with the same name / path in <generated-project>/app/App_Resources folder.
.xml files (Android): Only for files in App_Resources_Merge/Android/src/main folder. The merging is done by making use of the build variants concept in Android: Configure build variants, for src/main/AndroidManifest.xml, please follow: Merge multiple manifest files.

At first the XML files will be copied from .mdkproject/app/App_Resources_Merge to <generated-project>/app/App_Resources_Merge folder, and during the build process (after tns prepare hook), the XML files will be further copied to <generated-project>/platforms/android/app/src/debug and <generated-project>/platforms/android/app/src/release folders, then Android build process will merge them automatically.

!!! note "Note"

  Some files in `<generated-project>/platforms/android/app/src/debug/res` folder are created by NativeScript, please do check it and do not use the same file name / path for merging purpose to avoid issues.

Examples¶

Property List (`.plist`) Files¶

Update value of ExistKey1 / ExistKey2 (assume ExistKey1 & ExistKey1 exist already), add value of NewKey

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>ExistKey1</key>
    <array>
        <dict>
            <key>CFBundleURLName</key>
            <string>com.sap.SAPMDC</string>
            <key>CFBundleURLSchemes</key>
            <array>
                <string>sapmobilesvcs</string>
                <string>mdkclient2</string>
            </array>
        </dict>
    </array>
    <key>ExistKey2</key>
    <string>2.0</string>
    <key>NewKey</key>
    <string>NewValue</string>
</dict>
</plist>

iOS Xcode Configuration (`.xcconfig`) Files¶

Original file in template project: <mdk-template>/app/App_Resources/iOS/build.xcconfig

AnotherKey = Some Value
ExistingKey = Old Value

Overriding file: .mdk_project/App_Resources_Merge/iOS/build.xcconfig

#include "new.xcconfig"

ExistingKey = Updated Value
NewKey = New Value

Resulting file: <generated-project>/app/App_Resources/iOS/build.xcconfig:

#include "new.xcconfig"

AnotherKey = Some Value
ExistingKey = Updated Value
NewKey = New Value

String Resource (`.strings`) Files¶

Original file in template project: <mdk-template>/app/App_Resources/iOS/i18n/en.lproj/InfoPlist.strings

"AnotherKey" = "Some Value";
"ExistingKey" = "Old Value";

Overriding file: .mdk_project/App_Resources_Merge/iOS/i18n/en.lproj/InfoPlist.strings

"ExistingKey" = "Updated Value";
"NewKey" = "New Value";

Resulting file: <generated-project>/app/App_Resources/iOS/i18n/en.lproj/InfoPlist.strings:

"AnotherKey" = "Some Value";
"ExistKey" = "Updated Value";
"NewKey" = "New Value";

Gradle (`.gradle`) Files¶

The value of abiFilters will be changed to ['arm64-v8a','x86_64']

// Add your native dependencies here:
println '---------------------------Merge APP.GRADLE---------------------------------'

android {
  defaultConfig {  
    ndk {
      abiFilters.clear()
      abiFilters.addAll(['arm64-v8a','x86_64'])
    }
  }
}

XML (`.xml`) Files¶

This applies to the XML files in App_Resources_Merge/Android/src/main folder only.

Example with src/main/AndroidManifest.xml:

Add new permission: ACCESS_WIFI_STATE, remove permission: READ_EXTERNAL_STORAGE, add uses-library setting in application element

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="__PACKAGE__"
    xmlns:tools="http://schemas.android.com/tools"
    android:versionCode="1"
    android:versionName="1.0">

    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" tools:node="remove"/>
    <application>
        <uses-library android:name="com.dummy.mdk" android:required="false"/>
    </application>
</manifest>

Example for other xml files in Android, e.g. src/main/res/values/styles.xml:

Change actionMenuTextColor to #FFF8C471

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:android="http://schemas.android.com/apk/res/android">
  <style name="MDKAppTheme" parent="FioriTheme">
      <item name="android:actionMenuTextColor">#FFF8C471</item>
  </style>
</resources>

Last update: November 18, 2021

Overriding App Resources¶

Supported File Types¶

Examples¶

Property List (.plist) Files¶

iOS Xcode Configuration (.xcconfig) Files¶

String Resource (.strings) Files¶

Gradle (.gradle) Files¶

XML (.xml) Files¶

Property List (`.plist`) Files¶

iOS Xcode Configuration (`.xcconfig`) Files¶

String Resource (`.strings`) Files¶

Gradle (`.gradle`) Files¶

XML (`.xml`) Files¶