Home
GuidesAPI ReferenceRelease Notes
HomeLog InHome
Guides
Home
  1. SDK Android

Compose widgets - Android

Compose widgets integration Guide

There is a suite of Compose widgets to streamline the integration of Stories and Moments in various widget layouts. These widgets bridge traditional Android views with the Composable architecture, ensuring flexibility while leveraging the power of Jetpack Compose.

  1. BlazeComposeStoriesWidgetGridView - This represents a Blaze widget Composable for Stories with a grid layout on a vertical axis.
  2. BlazeComposeStoriesWidgetRowView - This represents a Blaze widget Composable for Stories with a row layout on a horizontal axis.
  3. BlazeComposeMomentsWidgetGridView - This represents a Blaze widget Composable for moments with a grid layout on a vertical axis.
  4. BlazeComposeMomentsWidgetRowView - This represents a Blaze widget Composable for moments with a row layout on a horizontal axis.
  5. BlazeComposeVideosWidgetGridView - This represents a Blaze widget Composable for videos with a grid layout on a vertical axis.
  6. BlazeVideosWidgetRowView - This represents a Blaze widget Composable for videos with a row layout on a horizontal axis.
📘

Widgets will notify if any data exists for display.

Widget doesn't provide empty state UI display.
App developers should make sure to decide on proper logic for empty state.

Implementation

Prerequisites

  • Ensure Jetpack Compose is integrated into your project.

Widget initialization

Stories row

BlazeComposeStoriesWidgetRowView(
    modifier: Modifier = Modifier,
    widgetStoriesStateHandler = BlazeComposeWidgetStoriesStateHandler(...)
)

Stories grid

BlazeComposeStoriesWidgetGirdView(
    modifier: Modifier = Modifier,
    widgetStoriesStateHandler = BlazeComposeWidgetStoriesStateHandler(...)
)

Moments row

BlazeComposeMomentsWidgetRowView(
    modifier: Modifier = Modifier,
    widgetMomentsStateHandler = BlazeComposeWidgetMomentsStateHandler(...)
)

Moments grid

BlazeComposeMomentsWidgetGridView(
    modifier: Modifier,
    widgetMomentsStateHandler = BlazeComposeWidgetMomentsStateHandler(...)
)

Videos row

BlazeComposeVideosWidgetRowView(
    modifier: Modifier = Modifier,
    widgetVideosStateHandler = BlazeComposeWidgetVideosStateHandler(...)
)

Videos grid

BlazeComposeVideosWidgetGridView(
    modifier: Modifier,
    widgetVideosStateHandler = BlazeComposeWidgetVideosStateHandler(...)
)

Stories

Handling stories widget state: BlazeComposeWidgetStoriesStateHandler

BlazeComposeWidgetStoriesStateHandler class acts as a central point for handling widget states and actions, ensuring that interactions with the widget are processed and managed efficiently.

Creation ofBlazeComposeWidgetStoriesStateHandler

Each BlazeComposeWidgetStoriesStateHandler instance must be associated with a unique widgetId to ensure proper management and avoid conflicts. It's crucial to instantiate BlazeComposeWidgetStoriesStateHandler at the top of the Compose tree to ensure it's initialized before any associated widgets or Lazy Component.

// Choose whatever presets works for you
val widgetItemStyle = BlazeWidgetLayout.Presets.StoriesWidget.Row.circles

val widgetHandler: BlazeComposeWidgetStoriesStateHandler? = BlazeComposeWidgetStoriesStateHandler(
  widgetLayout = widgetItemStyle,
  playerStyle = BlazeStoryPlayerStyle.base(),
  dataSourceType = BlazeDataSourceType.Labels(BlazeWidgetLabel.singleLabel("some-label")),
  widgetId = "simpleID-stories-widget",
  // If a widget with this identifier exists in the CMS, its layout (UI) and data source are derived from there.
  widgetRemoteIdentifier = "remote-widget-id-stories-widget",
  shouldOrderWidgetByReadStatus: Boolean = true,
  cachingLevel = BlazeCachingLevel.DEFAULT,
  widgetDelegate = object : BlazeWidgetDelegate {
    // Here is your optional implementation
  },
  perItemStyleOverrides = mapOf(
    BlazeWidgetItemCustomMapping(
      key = "someKey",
      value = "someValue"
    ) to BlazeWidgetItemStyleOverrides(
      // Make sure to deep copy before modifying any value!
      statusIndicator = widgetItemStyle.statusIndicator.blazeDeepCopy().apply {
        // Whatever changes needs to be made on the status indicator 
      },

      // Make sure to deep copy before modifying any value!
      badge = widgetItemStyle.badge.blazeDeepCopy().apply {
        // Whatever changes needs to be made on the badge
      }
    )
  ),
  onWidgetItemClickHandler = object : BlazeWidgetItemClickHandlerState {
    // Here is your optional implementation
  }
)

Moments

Handling Moments widget state: BlazeComposeWidgetMomentsStateHandler

BlazeComposeWidgetMomentsStateHandler class acts as a central point for handling widget states and actions, ensuring that interactions with the widget are processed and managed efficiently.

Creation ofBlazeComposeWidgetMomentsStateHandler

Each BlazeComposeWidgetMomentsStateHandler instance must be associated with a unique widgetId to ensure proper management and avoid conflicts. It's crucial to instantiate BlazeComposeWidgetMomentsStateHandler at the top of the Compose tree to ensure it's initialized before any associated widgets or Lazy Component.


// Choose whatever presets works for you
val widgetItemStyle = BlazeWidgetLayout.Presets.MomentsWidget.Row.verticalRectangles

val widgetHandler: BlazeComposeWidgetMomentsStateHandler? = BlazeComposeWidgetMomentsStateHandler(
  widgetLayout = widgetItemStyle,
  playerStyle = BlazeMomentsPlayerStyle.base(),  dataSourceType = BlazeDataSourceType.Labels(BlazeWidgetLabel.singleLabel("some-label")),
    widgetId = "simpleID-moments-widget",
    // If a widget with this identifier exists in the CMS, its layout (UI) and data source are derived from there.
    widgetRemoteIdentifier = "remote-widget-id-moments-widget",
    shouldOrderWidgetByReadStatus: Boolean = true,
    cachingLevel = BlazeCachingLevel.DEFAULT,
    widgetDelegate = object : BlazeWidgetDelegate {
      // Here is your optional implementation
    },
    perItemStyleOverrides = mapOf(
      BlazeWidgetItemCustomMapping(
        key = "someKey",
        value = "someValue"
      ) to BlazeWidgetItemStyleOverrides(
        // Make sure to deep copy before modifying any value!
        statusIndicator = widgetItemStyle.statusIndicator.blazeDeepCopy().apply {
          // Whatever changes needs to be made on the status indicator 
        },

        // Make sure to deep copy before modifying any value!
        badge = widgetItemStyle.badge.blazeDeepCopy().apply {
          // Whatever changes needs to be made on the badge
        }
      )
    ),
    onWidgetItemClickHandler = object : BlazeWidgetItemClickHandlerState {
      // Here is your optional implementation
    }
)

Videos

Handling Videos widget state: BlazeComposeWidgetVideosStateHandler

BlazeComposeWidgetVideosStateHandler class acts as a central point for handling widget states and actions, ensuring that interactions with the widget are processed and managed efficiently.

Creation ofBlazeComposeWidgetVideosStateHandler

Each BlazeComposeWidgetVideosStateHandler instance must be associated with a unique widgetId to ensure proper management and avoid conflicts. It's crucial to instantiate BlazeComposeWidgetVideosStateHandler at the top of the Compose tree to ensure it's initialized before any associated widgets or Lazy Component.


// Choose whatever presets works for you
val widgetItemStyle = BlazeWidgetLayout.Presets.VideosWidget.Row.verticalRectangles

val widgetHandler: BlazeComposeWidgetVideosStateHandler? = BlazeComposeWidgetVideosStateHandler(
  widgetLayout = widgetItemStyle,
  playerStyle = BlazeVideosPlayerStyle.base(),  
  dataSourceType = BlazeDataSourceType.Labels(BlazeWidgetLabel.singleLabel("some-label")),
    widgetId = "simpleID-videos-widget",
    // If a widget with this identifier exists in the CMS, its layout (UI) and data source are derived from there.
    widgetRemoteIdentifier = "remote-widget-id-videos-widget",
    shouldOrderWidgetByReadStatus: Boolean = true,
    cachingLevel = BlazeCachingLevel.DEFAULT,
    widgetDelegate = object : BlazeWidgetDelegate {
      // Here is your optional implementation
    },
    perItemStyleOverrides = mapOf(
      BlazeWidgetItemCustomMapping(
        key = "someKey",
        value = "someValue"
      ) to BlazeWidgetItemStyleOverrides(
        // Make sure to deep copy before modifying any value!
        statusIndicator = widgetItemStyle.statusIndicator.blazeDeepCopy().apply {
          // Whatever changes needs to be made on the status indicator 
        },

        // Make sure to deep copy before modifying any value!
        badge = widgetItemStyle.badge.blazeDeepCopy().apply {
          // Whatever changes needs to be made on the badge
        }
      )
    ),
    onWidgetItemClickHandler = object : BlazeWidgetItemClickHandlerState {
      // Here is your optional implementation
    }
)

Full example

To demonstrate the correct work-flow using the Compose widgets, we will explain using BlazeComposeStoriesWidgetRowView example (same for other Compose widgets as well):

  1. Creating the state handler:
    1. Each BlazeComposeWidgetStoriesStateHandler instance must be associated with a unique widgetId to ensure proper management and avoid conflicts.
    2. It's crucial to instantiate BlazeComposeWidgetStoriesStateHandler at the top of the Compose tree to ensure it's initialized before any associated widgets or Lazy Component.
val widgetStateHandler = BlazeComposeWidgetStoriesStateHandler( ... )

  1. Composing the widget:

    1. Incorporate BlazeComposeStoriesWidgetRowView into the desired location within your Composable hierarchy.
    2. Pass the previously created widgetStateHandler as a parameter to the BlazeComposeStoriesWidgetRowView.
    3. The widgetStateHandler now actively manages the state and interactions of the BlazeComposeStoriesWidgetRowView
    BlazeComposeStoriesWidgetRowView(
  modifier = Modifier,
  widgetStoriesStateHandler = widgetStateHandler
)

  2. Interacting with the widget:

    1. Utilize the methods and properties of widgetStateHandler to control and interact with BlazeComposeStoriesWidgetRowView.
    2. This includes reloading data, updating configurations, and handling user interactions.
    widgetStateHandler.reloadData()

Important note:

  • Each instance of BlazeComposeStoriesWidgetRowView should be paired with a unique BlazeComposeWidgetStoriesStateHandler.
  • It's imperative to create BlazeComposeWidgetStoriesStateHandler at the top of your Compose tree to ensure correct state management and lifecycle handling.
  • This approach provides fine-grained control over each widget instance and facilitates effective state synchronization.

StateHandler methods

BlazeComposeWidgetStoriesStateHandler, BlazeComposeWidgetMomentsStateHandler & BlazeComposeWidgetVideosStateHandler Methods

Both BlazeComposeWidgetStoriesStateHandler and BlazeComposeWidgetMomentsStateHandler have the same methods as the native widgets. Please visit Widget Methods.

Example usage of state handler -> BlazeComposeWidgetStoriesStateHandler methods

Once you have a BlazeComposeWidgetStoriesStateHandler instance, you can utilize its methods to manage the widget's state.

// Example of using reloadData
widgetHandler?.reloadData(isSilentRefresh = true)

// Example of updating the data source
widgetHandler?.updateDataSource(newDataSourceType)

// Example of updating the ads config type
widgetHandler?.updateAdsConfigType(newStoriesAdsConfigType)

// Example of updating styles overrides
widgetHAndler?.updateOverrideStyles(newPerItemStyleOverrides)

Properties

Please visit the Widgets Properties section.

Updated 22 days ago

Did this page help you?