StorytellerClipsListView

Note: All of the example code snippets are using the StorytellerClipsRowView type, however, if you are using StorytellerClipsGridView they will work in exactly the same way.

StorytellerClipsListView is a base abstract class for views displaying lists of Clips. The Storyteller SDK offers two implementations of this abstract class:

• StorytellerClipsRowView (see StorytellerClipsRowView)
• StorytellerClipsGridView (see StorytellerClipsGridView)

Attributes

This sections describes attributes common to StorytellerClipsRowView (see StorytellerClipsRowView) and StorytellerClipsGridView (see StorytellerClipsGridView). Notes are used to mark if there is a difference in property interpretation

StorytellerClipsListView base class attributes:

• delegate: the StorytellerListViewDelegate instance for StorytellerClipsListView callbacks (see Implementing StorytellerListViewDelegate methods)
• collection: the Collection that the list view should show to the user. The default value is null - see below for more details
• theme: This parameter is used to set the Theme for the StorytellerClipsListView. If theme is set to null, then theme set asStoryteller.theme global property is used. The theme determines how the items within the List View are presented as well as various features of the player once it is launched.
• displayLimit: only display up to this number of tiles in the list.
• uiStyle: adjust whether Storyteller renders in light mode, dark mode or follows the system setting.

uiStyle takes the following values:

• StorytellerListViewStyle.AUTO - default value, the StorytellerClipsListView will adjust its color scheme automatically according to the current system UI mode
• StorytellerListViewStyle.LIGHT - force the StorytellerClipsListView to use the light theme
• StorytellerListViewStyle.DARK - force the StorytellerClipsListView to use the dark theme

Collection

The collection property is used to show specific Clips content in the row or grid by supplying a single Collection as string. Collections can be defined in the CMS. If no Collection is assigned, then no Clips content is displayed.

Example:

    val storytellerClipsRowView = StorytellerClipsRowView()
    storytellerClipsRowView.collection = "collectionId"
    storytellerClipsRowView.reloadData()

Feed Title

The feed title in the Clips player can be configured in the CMS for the Collection. This can be a custom title or image.

Theme

The theme used to render Clips items in the list. It will also be passed to activities launched from this ClipsListView.

Example:

    val storytellerClipsRowView = StorytellerClipsRowView()
    val customTheme: UiTheme
    //~~~ build customized theme UITheme ~~ //
    storytellerClipsRowView.theme = customTheme

Dynamic Scaling

Item tiles will scale dynamically to fit the row or grid view.

The base size of the tiles are:

• 100dp width x 150dp height for square tiles
• 76dp width x 105dp height for round tiles

The base size will be used when rendering the row if the dimensions of the row view cannot determine its constraints. The exact dimensions of the row view will depend on how it is defined in the layout view hierarchy, including its parents. In general, tiles will maintain its base proportions and scale up or down to meet view hierarchy constrains.

For the sake of simplicity, examples will be provided using square as 100dp/150dp = 2/3 proportions to make it easier to do calculations.

Example 1

    <com.storyteller.ui.list.StorytellerClipsRowView
      app:cellType="square"
      android:layout_width="match_parent"
      android:layout_height="200dp"
      ...
    />

The final item tile size will be ≈ 133dp x 200dp, as 200 dp[h] * 2/3 [w/h] ≈ 133dp

Example 2

  <LinearLayout
  android:layout_width="match_parent"
  android:layout_height="200dp"
  android:orientation="vertical">
    <com.storyteller.ui.list.StorytellerClipsRowView
      app:cellType="square"
      android:layout_width="match_parent"
      android:layout_height="match_parent"
      ...
    />
  </LinearLayout>

The final item tile size will be ≈ 133dp x 200dp. This is because the StorytellerRowView is wrapped in a parent view with a height of 200dp and has its size attributes set to match_parent. The system, therefore, expands the row view to fill the height of its parent and scales the width of the tiles accordingly.

Example 3

  <?xml version="1.0" encoding="utf-8"?>
    <com.storyteller.ui.list.StorytellerClipsRowView
    app:cellType="square"
    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="wrap_content"
    android:layout_height="match_parent"
    ...
  />

In this case, the final item tile size will be the height of the window. This happens because the StorytellerRowView is defined as the top-most view and android:layout_height="match_parent" has been set on the view. The system, therefore, expands the row view to fill the window height - and so the resulting item tiles will scale to fit the window height also.

Example 4

  ...

  <LinearLayout
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:orientation="vertical">

    <com.storyteller.ui.list.StorytellerClipsRowView
      app:cellType="square"
      android:layout_width="match_parent"
      android:layout_height="wrap_content"
      ...
    />

    ...

  </LinearLayout>

In this case, the final item tile size will be 100dp x 150dp (the base size). Since the StorytellerRowView has been defined as the child of another view, setting android:layout_height="wrap_content" makes the item tile size 100dp x 150dp (base size).

XML

Attributes can also be applied in XML.

<com.storyteller.ui.list.StorytellerClipsRowView
    android:layout_width="match_parent"
    android:layout_height="wrap_content"/>

Methods

reloadData

The reloadData method starts loading fresh data for all Clips from the API. On completion, it updates the Clips data, starts prefetching content and updates the read status of the Clips. The onDataLoadStarted and onDataLoadComplete methods on the StorytellerListViewDelegate are called accordingly (the latter with appropriate data depending on the result of the API requests).

val storytellerClipsRowView = StorytellerClipsRowView(context)
storytellerClipsRowView.reloadData()