Android Theming

Foreword

Due to properties of the Android theming system, no special runtime / code based theme customization can be done at this time. However, the native method of the Sensibill Android SDK customization method can still be achieved.

Info

Android theme customization will be easier if Android Studio is used.

This will involve creating and editing some Android xml resoruce files.

Extra details and assumptions will be outlined here as a refresher on Android project structure.

Assumptions Within this Android section, a few assumptions will be made:

  • We assume your project has a standard structure, specifically:
    • /android is a folder containing the android-specific code for the project
    • The /android/app folder exists, and is the root for the Android app module’s code

If you have not made any significant Android subproject changes from the project structure generated by react-native init, the above assumptions should hold true. If they do not, please keep these assumptions in mind when following further instructions.

Terminology & References

  • Filepaths with a leading / will refer to a path relative to the project root
  • The Android “resources folder” is located at /android/app/src/main/res
    • Most, if not all theming customization will be done within this resources folder
    • The resources folder contains subfolders for resource categories. Each subfolder contains xml files defining various Android resources
      • Terminology-wise, we will refer to these resource folders by their category, then “resources folder”. Therefore, the “values resources folder” would mean the " /android/app/src/main/res/ values/ " folder.

Creating a Custom Theme

In the Android resources, the Android Sensibill SDK provides numerous exposed styles for integrators to override in order to customize the visual experience of the SDK.

To begin creating a customized theme, create an XML file in the values resources folder (/android/app/src/main/res/values/) (create the folder if it does not already exist). It can be called styles.xml if a file of that name does not yet exist, or can be named something else such as sensibill_styles.xml.

Next, add a top level <resources> tag:

<resources>

</resources>

Finally, add the following style entry exactly to begin customizing the Capture Standalone Theme:

<resources>
    <style name="New.Theme.Sensibill.CaptureStandalone" parent="Base.New.Theme.Sensibill.CaptureStandalone" >

    </style>
</resources>

This style entry states that you want to customize the New.Theme.Sensibill.CaptureStandalone style, and that it extends the Base.New.Theme.Sensibill.CaptureStandalone style (our baseline theme). The New.Theme.Sensibill.CaptureStandalone style is used by all Sensibill Capture pages, and therefore they will inherit the custoimzation provided here.

Now that you have your empty style override entry, customization can begin by adding theme element overrides within it.

As an example, in order to change the primary colour to red, and the capture background colour to dark grey, your style file will end up looking like this:

<resources>
    <style name="New.Theme.Sensibill.CaptureStandalone" parent="Base.New.Theme.Sensibill.CaptureStandalone" >
    <!-- Main Theme Colours -->
    <item name="sb__colourPrimary">#FF0000</item>

    <!-- Capture Colours -->
    <item name="sb__colourCaptureBackground">#222222</item>
    </style>
</resources>

To determine exactly what themed elements to customize, the main SDK documentation will be very useful (use the “Android” tab in docs):

Definition of the main colour pallette

Main SDK Theme customization

Capture Theme Customization (Scroll down to “Customize The Standalone Capture Theme” in the Android tab)

Additionally, detailed theme customization instructions for capture will be provided in the next section.



Theme Elements Required for Capture

The Sensibill Standalone Capture module doesn’t use the entirety of the Sensibill theme.

This section provides a detailed breakdown of all theme elements required to fully customize the Capture experience.

Within the descriptions, the “diagram” will refer to the diagram image near the top of the “Theme Customization” section of this page

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <style name="New.Theme.Sensibill.CaptureStandalone" parent="Base.New.Theme.Sensibill.CaptureStandalone">

        <!-- Capture Theme -->
        <!--
            See diagram, `captureBackground` and `onCaptureBackground` are
            used for view "framing" within capture, as well as items that will be displayed
            on said frame.
        -->
        <item name="sb__colourCaptureBackground">#331111</item>
        <item name="sb__colourOnCaptureBackground">#AFDEDE</item>
        <item name="sb__colourOnCaptureBackgroundDisabled">#D4E2E2</item>



        <!-- Main SDK Theme -->
        <!--
            The `primary` and `onPrimary` colours are used for:
            - Primary buttons (see diagram)
            - Capture progress indicator (see diagram, `primary` only)
            - Crop bounds indicator (see diagram, `primary` only)
         -->
        <item name="sb__colourPrimary">#8B3B60</item>
        <item name="sb__colourOnPrimary">#FFFFFF</item>
        <!-- `primaryVariant` is used as the background for the capture tips screen -->
        <item name="sb__colourPrimaryVariant">#53283C</item>

        <!-- `secondary` and `onSecondary` colours are used for secondary buttons (see diagram) -->
        <item name="sb__colourSecondary">#3B8B66</item>
        <item name="sb__colourOnSecondary">#FFFFFF</item>

        <!-- 
            `surface` and `onSurface` colours are used for:
            - Default background and text colour of alert dialogs (popups)
            - Tips screen:
                - Unselected tab indicator (`surface` only)
                - "Next" button (`surface` background, `onSurface` text)
         -->
        <item name="sb__colourSurface">#FFE9B6</item>
        <item name="sb__colourOnSurface">#513F16</item>

    </style>
</resources>

Using A Custom Font

(Android docs reference)

Applying a custom font to the Sensibill Standalone Capture module can be achieved by editing android resources.

The steps to accomplish this are:

  1. Add font files
  2. Create font family
  3. Add to theme
Add Font Files

First, create a font resources folder (/android/app/src/main/res/font). Then, copy all necessary .ttf font files to the font resources folder.

NOTE: You may have to rename your font files to make them compatible with the Android resources naming convention - in that only lowercase letters and underscores are allowed. eg. a file named MyFavouriteFont-Italic.ttf should be renamed to my_favourite_font_italic.ttf. If this is not done, Android will not parse the files and the following steps will not work.

Create Font Family

Now, you must create an Android font family that includes the fonts you’ve imported and wish to use. The steps to do so are as follows.

First, create two <my_font_name>_font_family.xml files, one in the font resources folder (/android/app/src/main/res/font), and one in the font-v26 resources folder (/android/app/src/main/res/font-v26). These separate files are required for compatibility with old and new Android versions.

Next, populate the files appropriately. This will consist of creating a font-family tag containing the required font tags.

Normally, this will be two separate font tags, one containing the regular font, and one containing the italic version. Each font tag will include entries for:

  • <app/android>:font - a reference to the actual font file, in the form of @font/<font filename without extension>
  • <app/android>:fontStyle - normal or italic, usually you’ll include one of each
  • <app/android>:fontWeight - The font weight, 400 for normal weight

Use the below example as a template for your font family resource files.

<!-- res/values/font/<my_font_name>_font_family.xml -->
<?xml version="1.0" encoding="utf-8"?>
<font-family xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:app="http://schemas.android.com/apk/res-auto">
  <font
    app:font="@font/my_favourite_font_regular"
    app:fontStyle="normal"
    app:fontWeight="400" />
  <font
    app:font="@font/my_favourite_font_italic"
    app:fontStyle="italic"
    app:fontWeight="400" />

</font-family>


<!-- res/values/font-v26/<my_font_name>_font_family.xml -->
<?xml version="1.0" encoding="utf-8"?>
<font-family xmlns:android="http://schemas.android.com/apk/res/android">
  <font
    android:font="@font/my_favourite_font_regular"
    android:fontStyle="normal"
    android:fontWeight="400" />
  <font
    android:font="@font/my_favourite_font_italic"
    android:fontStyle="italic"
    android:fontWeight="400" />

</font-family>
Add to Theme

The final step is to set your newly created font family as the default font for the theme. In your values resources folder (/android/app/src/main/res/values/) styles file in which you added the New.Theme.Sensibill.CaptureStandalone style, add references to the font family you created above.

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <style name="New.Theme.Sensibill.CaptureStandalone" parent="Base.New.Theme.Sensibill.CaptureStandalone">
        <!-- Font -->
        <!-- Add Font font family here, replacing `my_font_name` with your own font name -->
        <item name="fontFamily">@font/my_font_name_font_family</item>
        <item name="android:fontFamily">@font/my_font_name_font_family</item>

        <!-- Other theme custoimzation... -->
    </style>
</resources>