Custom Themes

The appearance of the SDK can be customized by setting the Storyteller.theme global property or StorytellerListView.theme view property. This requires a UiTheme configuration object.

Note: global theme should be set before any of the Storyteller list views are inflated. Note: this property will be used as fallback theming style used to render Story items in lists and activities launched from list. See StorytellerListView.

UiTheme is a data structure containing tree of the parameters. While it's possible to manually declare a whole structure of this data object, for convenience it's recommended to use UiTheme DSL for that purpose.

Defining a Theme

A Theme contains various settings which change visual aspects of the Storyteller SDK. All properties are optional. In general, it should be possible to obtain a custom look by only using the colors properties - however, if you require more fine-grained control, that is also available.

Colors

The colors property on theme is used to establish a set of base colors for the SDK to use.

Font

Use the font property to set a custom font for use throughout the SDK.

Primitives

The primitives object contains base values which are used throughout the SDK.

Lists

The lists customize properties of the various list types available from the SDK.

Story Tiles

The storyTiles property can be used to customize the appearance of the Story Tiles.

Player

The player property is used to customize properties relating to the Story Player.

Buttons

The buttons property applies customizations to buttons which appear throughout the SDK.

Instructions

Use the instructions property to customize the appearance of the instructions screen.

Engagement Units

The engagementUnits property can be used to customize properties relating to Polls and Quizzes.

Theme DSL Usage

Theme Builder Initialization

Theme builder is initialized by the buildTheme(context) method lambda passed after the method acts in the builder scope.

import com.storyteller.domain.theme.builders.buildTheme
import com.storyteller.domain.theme.builders.ofHexCode

Storyteller.theme = buildTheme(context) {
  light.colors.primary = ofHexCode("#FF00FF")
}

Accessing Properties in the Builder Scope

There are 2 equivalent ways of accessing builder properties:

• By scopes

  buildTheme(context) {
  light {
    instructions {
      button {
        backgroundColor = ofHexCode("#00FF00")
        }
      }
    }
  }
  

• By properties

  buildTheme(context) {
    light.instructions.button.backgroundColor = ofHexCode("#00FF00")
  }
  

Both approaches produce the same effect.

Light and Dark Builder Variants

In the builder context two variants are present:

• light
• dark

Although they have an identical structure, they are build with the different set of fallbacks. For instance, default theme.storyTiles.circularTile.title.unreadTextColor will fallback to the default value of theme.colors.black.primary in the light mode or theme.colors.white.primary in the dark mode.

The selection of active themes will be done using current phone UI mode and StorytellerListView.uiStyle property value. See StorytellerListView for more details.

For coding convenience, if you do not intent use light and dark mode and relay on default fallback you can use from inline method to copy already set values from one theme to the other.

buildTheme(context) {
  light {
    colors {
      primary = ofHexCode("#FF00FF")
      success = ofHexCode("#00FF00")
    }
  }
  dark from light
}

The above code will set all properties of dark to the current state of the light builder. This method is useful to avoid lengthy typing - a common parameter can be assigned one and copied to the other variant.

Setting Properties of Particular Type

Colors

Color properties are expected to be Android @ColorInt. They can be initialized with anything that return such type e.g they can be resolved color from resources, Color.argb() Color.BLUE and so on. For convenience, ofHexColor(string) method is provided - it accepts 6 or 8 hex digits prefixed by the #

val red = ofHexColor("#FF0000")
val semiTransparentRed = ofHexColor("#55FF0000")

Note: when using resources colors mind that they are resolved at the moment of building theme, NOT at the moment of accessing.

Drawables

For the properties accepting Drawable type, any Drawable extending object can be provided.

val myTheme = buildTheme(context){
  light.engagementUnits.poll.selectedAnswerBorderImage = GradientDrawable(
    GradientDrawable.Orientation.BOTTOM_TOP,
    intArrayOf(Color.CYAN, Color.MAGENTA)
  )
}

Fonts

To support multiple weights for fonts, a font family xml resource is required. The SDK will automatically select a font for the appropriate weight when needed.

• Creating a font family resource custom_font.xml

<?xml version="1.0" encoding="utf-8"?>
<font-family xmlns:android="http://schemas.android.com/apk/res/android">
    <font
        android:fontWeight="200"
        android:font="@font/my_font_regular" />
    <font
        android:fontWeight="700"
        android:font="@font/my_font_bold" />
</font-family>

• Setting the font family as custom font property theme.font

font = ResourcesCompat.getFont(ctx, R.font.custom_font)

Example

val storyRowView = StoryRowView(context)

storyRowView.theme = buildTheme(context) {
      light {
        colors {
          primary = ofHexCode("#FF0000")
          success = ofHexCode("#00FF00")
          alert = ofHexCode("#C50511")
        }

        font = ResourcesCompat.getFont(ctx, R.font.custom_font)

        lists {
          row {
            tileSpacing = 8
            startInset = 12
            endInset = 12
          }
          grid {
            tileSpacing = 8
            columns = 2
          }
        }

        storyTiles {
          title {
            textSize = 11
            lineHeight = 13
            alignment = Gravity.START
          }
          rectangularTile {
            padding = 8
            unreadIndicator.alignment = Gravity.END
            unreadIndicator.textColor = ofHexCode("#000FF")
            unreadIndicator.textSize = 11
          }
        }
        buttons.cornerRadius = 24
        buttons.textCase = TextCase.UPPER
        instructions {
          icons {
            forward = ContextCompat.getDrawable(ctx, R.drawable.ic_forward_light)
            pause = ContextCompat.getDrawable(ctx, R.drawable.ic_pause_light)
            back = ContextCompat.getDrawable(ctx, R.drawable.ic_back_light)
            move = ContextCompat.getDrawable(ctx, R.drawable.ic__swipe_light)
          }
        }
      }
      dark from light
    }