API Development

Understanding the Android Material Theme

In Titanium SDK 3.3.0, Appcelerator started using the Android AppCompat library. This native library provided background compatibility for the ActionBar, resulting in a more consistent and unified visual representation of your Android apps across Android devices, especially those running Android 2.x.

To style Android apps under Titanium 3.x, you needed to create native Android Styles, often using third-party tools. These styles are essentially a package of 9-patch images that Android would use while rendering screens. This means that the colors you see on Android apps with this version of AppCompat, instead of being actual colors represented as HEX triplets, are for the most part images that are being stretched to fit the given screen space. This not only results in a piecemeal styling process, but also adds some additional files to your app, increasing its ultimate file size.

As opposed to iOS where you can change virtually any visual style at runtime, on Android some styling takes place at build time, before the app is launched.

In SDK 4.0, Appcelerator is now using AppCompatv21, the most recent version of this library, which not only continues to provide backwards compatibility, but also now supports the Android Material Theme. Using the Material Theme is the first step in implementing elements of Material Design on your apps, and understanding it will make your app feel modern and consistent with the newest Android visual language.

Configuring your app to use Android Styles

By default, Android apps compiled with Titanium 4.x will use the Material Dark theme – your apps will be black with white text. You can override this theme by providing some extra details to the Android section of your tiapp.xml file.

<android xmlns:android="https://schemas.android.com/apk/res/android">
        <uses -sdk android:minSdkVersion="14" android:targetSdkVersion="22"></uses>
        <application android:theme="@style/LightDarkBar"></application>

In the code above, we’re re-configuring the native Android manifest file. First we tell Android that we’re targeting API Level 22 (Android 5.1), but support as low as API Level 14 (Android 4.0.x). More information about API Levels can be found at https://developer.android.com/guide/topics/manifest/uses-sdk-element.html.

We then say that our app will use a theme named LightDarkBar. This theme name is reminiscent of the legacy Android Holographic Themes, and can be applied to better provide background compatibility, in case your apps were built for Holo Themes. To implement them, go to platform/android/res/values/ and create a file called mytheme.xml (the name is not important – Android will grab the XML file within this folder). Inside this file add the following code.

< ?xml version="1.0" encoding="utf-8"?>
    <resources xmlns:android="https://schemas.android.com/apk/res/android">
        <style name="LightDarkBar" parent="Theme.AppCompat.Light.DarkActionBar"></style>
        <style name="Light" parent="Theme.AppCompat.Light"></style>
        <style name="Dark" parent="Theme.AppCompat"></style>

In the code above we’ve created three themes: LightDarkBar, Light and Dark, and have specified that they are derived from the ones provided by the AppCompat library itself. Having done this you can reconfigure your tiapp.xml to use either one, effectively overriding the default theme.

Customizing the Material Theme

One of the main advantages of the Material Theme, as far as styling is concerned, is that it no longer relies on 9-patch images that need to be bundled with your app – styling now is much easier to apply. One important thing to note though, is that in order to provide a more consistent user experience across all apps, Android now provides fewer customization options. Android will allow you to customize some key areas of your app while making sure it doesn’t break the overall Android user experience. See example below.

You can also specify the color you wish to use as a highlight when options are activated.

To implement these changes in your Android apps, go back to your platform/android/res/values/mytheme.xml file, and replace its contents with the following template.

< ?xml version="1.0" encoding="utf-8"?>
    <style name="Theme.Appcelerator" parent="@style/Theme.AppCompat.Light">
      <item name="colorPrimary">@color/primary</item>
      <item name="colorPrimaryDark">@color/primaryDark</item>      
      <item name="colorAccent">@color/primaryDark</item>
      <item name="colorControlHighlight">@color/colorHighlight</item>      
      <item name="colorControlActivated">@color/colorActivated</item>      
      <item name="android:navigationBarColor">@color/primary</item>
      <item name="android:statusBarColor">@color/primaryDark</item>
      <item name="android:textColorPrimary">@color/textPrimary</item>
    <color name="colorActivated">#caeeff</color>
    <color name="primary">#C41230</color>
    <color name="primaryDark">#9E0C24</color>
    <color name="textPrimary">#000</color>
    <color name="accent">#FFCCD4</color>
    <color name="colorHighlight">#ffaaff</color>

Notice that for convenience, I’ve added the color names at the bottom as variables, making them easier to change. The example above is named Theme.Appcelerator, so make sure you make the required changes to tiapp.xml as seen below.

<android xmlns:android="https://schemas.android.com/apk/res/android">
        <application android:theme="@style/Theme.Appcelerator"></application>
        <uses -sdk android:minSdkVersion="14" android:targetSdkVersion="22"></uses>

There’s much more to Material Design – this blog post explains how to implement the Material Theme to make your app look modern and more consistent with newer Android devices. There are other features currently being worked on such as Elevation and Shadow Support. Make sure you follow this topic in Jira to know when the rest of the features are made available.