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 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

Font

Primitives

Lists

Story tiles

Player

Buttons

Instructions

Engagement units

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 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.

Selection of active theme will be done using current phone UI mode and StorytellerListView.uiStyle property value. See StorytellerListView

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
}

Above code will set all properties of dark to the current state of light builder. This method is useful to avoid lengthy typing - 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 was 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)
  )
}

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
    }```