Configuring a StorytellerListView

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

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

• StorytellerRowView (see StorytellerRowView)
• StorytellerGridView (see StorytellerGridView)

Attributes

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

StorytellerListView base class attributes:

• cellType: the style of cell, it can be either ROUND(0) or SQUARE(1), default value is SQUARE(1)
• delegate: the StorytellerListViewDelegate instance for StorytellerListView callbacks (see Implementing StorytellerListViewDelegate methods)
• categories: the list of Categories that the list view should show to the user. The default value is an empty list - see below for more details
• theme: This parameter is used to set the Theme for the StorytellerListView. 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.
• uiStyle: adjust whether Storyteller renders in light mode, dark mode or follows the system setting.
• displayLimit: only display up to this number of tiles in the list.

uiStyle takes the following values:

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

Categories

The categories property can be used to show specific Stories content in the row or grid by supplying a list of valid Categories as strings. Categories can be defined in the CMS. If no Categories are assigned then the content from the default or "Home" Category is displayed.

Example:

    val storytellerRowView = StorytellerRowView()
    storytellerRowView.categories = listOf("category1", "category2", "categoryX")

Theme

The theme used to render Story items in the list. In will also be passed to activities launched from this StoryRowView.

Example:

    val storytellerRowView = StorytellerRowView()
    val customTheme: UiTheme
    //~~~ build customized theme UITheme ~~ //
    storytellerRowView.theme = customTheme

Dynamic Scaling

Item tiles will scale dynamically to fit the row or grid view. The base size of the tiles is 104dp x 156dp. The base size will be used when rendering the row if the dimensions of the row view cannot determine its dimensions. The exact dimensions of the row view will depend on how it is defined in the layout view hierarchy, including its parents.

Example 1

    <com.storyteller.ui.list.StorytellerRowView
      android:layout_width="match_parent"
      android:layout_height="200dp"
      ...
    />

The final item tile size will be 133dp x 200dp.

Example 2

  <LinearLayout
  android:layout_width="match_parent"
  android:layout_height="200dp"
  android:orientation="vertical">
    <com.storyteller.ui.list.StorytellerRowView
      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.StorytellerRowView
    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"
    ...
  />

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="wrap_content" 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.StorytellerRowView
      android:layout_width="match_parent"
      android:layout_height="wrap_content"
      ...
    />

    ...

  </LinearLayout>

In this case, the final item tile size will be 104dp x 156dp (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 104dp x 156dp (base size).

StorytellerListViewCellType

The StorytellerListViewCellType enum can be used to set the cellType property in a StorytellerRowView

Example:

    val storytellerRow = StorytellerRowView(context)
    storytellerRowView.cellType = StorytellerListViewCellType.ROUND

XML

Attributes can also be applied in XML.

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

Methods

reloadData

The reloadData method starts loading fresh data for all Stories from the API. On completion, it updates the Story data, starts prefetching content and updates the read status of the Stories. 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 storytellerRowView = StorytellerRowView(context)
storytellerRowView.reloadData()

openStory

The openStory() method opens a specific Story by its id parameter, a UUID identifier returned from the API. If Story with id will not be found then the row or grid view will reload itself and try to find it again. If it fails then custom onError callback is called. If id is an empty string, invalid, or not specified the onError callback will be called so your app can handle this error.

Parameters:

• storyId: unique Story ID
• animated: specifies whether or not the open animation will be played
• onError: callback for an error

Example:

    val storytellerRow = StorytellerRowView(context)
    storytellerRow.openStory(storyId, true) { error ->
      //action to do on error
    }

openPage

The openPage() method opens a specific Page by its id parameter, a UUID identifier returned from the API. If Page with id will not be found then the list will reload itself and try to find the Page again. If it fails then custom onError callback is called. If id is an empty string, invalid, or not specified the onError callback will be called so your app can handle this error.

Parameters:

• pageId: unique Page ID
• animated: specifies whether or not the open animation will be played
• onError: callback for an error

Example:

    val storytellerRow = StorytellerRowView(context)
    storytellerRow.openPage(pageId, true) { error ->
      //action to do on error
    }

openDeepLink

The openDeepLink() method opens a specific Story or Page. If Story within url will not be found then the list will reload itself and try to find it again. If the link is an empty string, or invalid the onError callback will be called so your app can handle this error.

Parameters:

• storytellerDeepLink: valid Storyteller deep link
• animated: specifies whether or not the open animation will be played
• onError: callback for an error

Example:

    val storytellerRow = StorytellerRowView(context)
    storytellerRow.openDeepLink(url, true) { error ->
        //action to do on error
    }