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_Resourceswill be copied (and overwrite any existing files) to<generated-project>/app/App_Resourcesfolder. - Next, the files in
.mdkproject/App_Resources_Mergewill 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:
.plistfiles (iOS): This type of files will be merged using/usr/libexec/PlistBuddyto merge into the file with the same name / path in<generated-project>/app/App_Resourcesfolder.PlistBuddyis a macOS built-in tool from Apple for editing.plistfiles..xcconfigfiles (iOS): This type of files will be merged into the file with the same name / path in<generated-project>/app/App_Resourcesfolder. Value of existing keys will be replaced, new keys will be added..stringsfiles (iOS): This type of files will be merged into the file with the same name / path in<generated-project>/app/App_Resourcesfolder. Value of existing keys will be replaced, new keys will be added..gradlefiles (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_Resourcesfolder..xmlfiles (Android): Only for files inApp_Resources_Merge/Android/src/mainfolder. The merging is done by making use of the build variants concept in Android: Configure build variants, forsrc/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
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>
Replacing parameters: Following example shows how to replace certain parameters of extractNativeLibs in AndroidManifest.xml(/.mdkproject/App_Resources_Merge/Android/src/main) file using tools:replace:
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools">
<application android:extractNativeLibs="true"
android:roundIcon="@mipmap/icon_round"
tools:replace="android:extractNativeLibs,android:roundIcon">
</application>
</manifest>
For more information, refer to this document.