Prerequisites
Set up your repo user by following the steps described in Set up for Android development.
Set up the dependencies
To use Backbase Design System in your app, add the following dependencies to your app's build.gradle.kts file.
implementation("com.backbase.android.design:design-system:$design_system_version")
// optional - If you use PhoneInputView or CountrySelector.
implementation("com.backbase.android.design:country-core:$country_core_version")
// optional - Flags resources.
implementation("com.backbase.android.design:country-icons:country_icons_version")
Extend your theme
First, select the app theme—this can be either Theme.Backbase or its variation Theme.Backbase.Fullscreen, which delegates the handling of the window insets, system status bar, and system navigation bar to the consumer. Then you can extend the selected theme to add customizations.
<style name="AppTheme" parent="Theme.Backbase.Fullscreen">
<!-- Override theme attributes such as colors, elevations, etc. -->
</style>
Example usage
The following example shows how to create a BackbaseButton component and how to style it. After extending the theme in the previous step, it associates the style Widget.Backbase.Button.Primary with the buttonStylePrimary attribute, which we can style globally. The BackbaseButton supports multiple styles, see the button documentation for all available styles. All of these styles can be extended to determine what buttons look like globally.
1. Add the BackbaseButton to a layout:
<com.backbase.android.design.button.BackbaseButton
android:id="@+id/button"
style="?buttonStylePrimary"
tools:text="Click me!" />
- Create a theme extending the Widget.Backbase.Button.Primary style and override the attributes, in this case the background tint.
<style name="CustomButton" parent="Widget.Backbase.Button.Primary" >
<item name="backgroundTint">@color/custom_primary_button_background</item>
</style>
- Associate the created style with the attribute buttonStylePrimary in the theme file. This way all the primary buttons will have the new background.
<style name="AppTheme" parent="Theme.Backbase.Fullscreen">
<item name="buttonStylePrimary">@style/CustomButton</item>
</style>
Using Jetpack Compose
Prepare your project
- First, you will need to prepare your project for using Jetpack Compose. Enable Compose in your project.gradle file as follows:
android {
buildFeatures {
compose = true
}
}
- Then, you set the compiler extension version. To find correct version for Kotlin, see the compatibility map.
android {
composeOptions {
kotlinCompilerExtensionVersion = "1.3.2"
}
}
Add dependencies
- Add the design system dependencies to your project.gradle file.
dependencies {
implementation ("com.backbase.android.design:design-system-compose:1.0.0-beta04")
}
- Add any other dependencies you need. It is recommended that you add the Compose BOM and select the Compose libraries you want to use for your development.
dependencies {
val composeBom = platform("androidx.compose:compose-bom:2023.06.01")
implementation(composeBom)
androidTestImplementation(composeBom)
// Choose one of the following:
// Material Design 3
implementation("androidx.compose.material3:material3")
// or Material Design 2
implementation("androidx.compose.material:material")
// or skip Material Design and build directly on top of foundational components
implementation("androidx.compose.foundation:foundation")
// or only import the main APIs for the underlying toolkit systems,
// such as input and measurement/layout
implementation("androidx.compose.ui:ui")
}
- The following are examples of other useful libraries that you include to help in your development.
dependencies {
// Other dependencies you might want to use
// Android Studio Preview support
implementation("androidx.compose.ui:ui-tooling-preview")
debugImplementation("androidx.compose.ui:ui-tooling")
// UI Tests
androidTestImplementation("androidx.compose.ui:ui-test-junit4")
debugImplementation("androidx.compose.ui:ui-test-manifest")
// Optional - Included automatically by material, only add when you need
// the icons but not the material library (e.g. when using Material3 or a
// custom design system based on Foundation)
implementation("androidx.compose.material:material-icons-core")
// Optional - Add full set of material icons
implementation("androidx.compose.material:material-icons-extended")
// Optional - Add window size utils
implementation("androidx.compose.material3:material3-window-size-class")
// Optional - Integration with activities
implementation("androidx.activity:activity-compose:1.7.3")
// Optional - Integration with ViewModels
implementation("androidx.lifecycle:lifecycle-viewmodel-compose:2.6.1")
// Optional - Integration with LiveData
implementation("androidx.compose.runtime:runtime-livedata")
// Optional - Integration with RxJava
implementation("androidx.compose.runtime:runtime-rxjava2")
}
Example usage
Following the guide above should get your Mobile Design System for Compose all set. The following are examples of how you can use MDS Compose in your app.
Using ThemedComposeView as a root view for a fragment journey
This example uses Fragment.ThemedComposeView, which is a helper function included in the Mobile Design system. It creates a ComposeView that has the Mobile Design system theme with its children.
class ColorsScreen : Fragment() {
override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View {
return ThemedComposeView {
// your compose code
}
}
}
Using ThemedComposeView in XML
- Add ThemedComposeView to your XML.
<androidx.constraintlayout.widget.ConstraintLayout
xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
xmlns:tools="http://schemas.android.com/tools"
android:layout_width="match_parent"
android:layout_height="wrap_content">
<com.backbase.android.design.theme.ThemedComposeView
android:id="@+id/themedComposeView"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
app:layout_constraintEnd_toEndOf="parent"
app:layout_constraintStart_toStartOf="parent"
app:layout_constraintTop_toTopOf="parent"/>
- Set the composable content in your code.
override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
super.onViewCreated(view, savedInstanceState)
view.findViewById<ThemedComposeView>(R.id.themedComposeView)
.setContent {
Text(
text = "Hello from compose",
style = Theme.typography.headings.h2,
color = Theme.colors.semantic.danger.default
)
}
}
Using ThemedComposeView in a RecyclerView Holder
- Use the ThemedComposeView as an itemView of the holder.
- Set the composable content in the init block of the holder.
internal class TransactionsListItemViewHolder constructor(
private val configuration: AccountsAndTransactionsConfiguration,
context: Context,
) : RecyclerView.ViewHolder(
ThemedComposeView(context)
) {
private val composeView get() = itemView as ThemedComposeView
private var model by mutableStateOf<TransactionItem?>(null)
init {
composeView.setContent {
Content()
}
}
fun bind(model: TransactionItem) {
this.model = model
}
@Composable
private fun Content() {
val model = model ?: return
val rowItem = configuration.transactions.transactionRowItemProvider.provide(configuration, model)
val title = rowItem.title.resolveWithFallback(itemView.context, fallback = "").toString()
Text(text = title, style = Theme.typography.caption.medium, color = Theme.colors.semantic.danger.default)
}
}
- Learn more about the ViewCompositionStrategy.
Using design tokens from the ThemedComposeView
All design tokens that are available in XML are also available in Compose. Use them as such:
// Example token path
Theme.colors.primary.default
Using PreviewTheme to apply the BackbaseTheme
The default theme is R.style.Theme_Backbase_Fullscreen, but you can set any theme.
@Composable
@Preview
internal fun ColorScreenPreview() {
PreviewTheme {
Column {
TypographyColors()
}
}
}