Note: All of the example code snippets are using the
StorytellerRowView
type, however, if you are usingStorytellerGridView
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
StorytellerGridView
This sections describes attributes common to StorytellerRowView
and StorytellerGridView
.
Notes are used to mark if there is a difference in property interpretation.
StorytellerListView base class attributes:
The cellType
is the style of the cell. This can either be ROUND(0)
or SQUARE(1)
. The default value is SQUARE(1)
.
The delegate
is the StorytellerListViewDelegate
instance for StorytellerListView
callbacks (see Implementing StorytellerListViewDelegate methods).
The categories
attribute is a list of Categories that the list view should show to the user. The default value is an empty list - see below for more details.
The theme
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.
The uiStyle
adjusts whether Storyteller renders in light mode, dark mode or follows the system setting.
The displayLimit
is the maximum amount of tiles that can be shown 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 modeStorytellerListViewStyle.LIGHT
- force the StorytellerListView to use the light themeStorytellerListViewStyle.DARK
- force the StorytellerListView to use the dark themeThe 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")
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
Item tiles will scale dynamically to fit the row or grid view.
The base size of the tiles are:
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 proportion 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.
<com.storyteller.ui.list.StorytellerRowView
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
<LinearLayout
android:layout_width="match_parent"
android:layout_height="200dp"
android:orientation="vertical">
<com.storyteller.ui.list.StorytellerRowView
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.
<?xml version="1.0" encoding="utf-8"?>
<com.storyteller.ui.list.StorytellerRowView
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.
...
<LinearLayout
android:layout_width="match_parent"
android:layout_height="match_parent"
android:orientation="vertical">
<com.storyteller.ui.list.StorytellerRowView
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).
The StorytellerListViewCellType
enum can be used to set the cellType
property in a StorytellerRowView
Example:
val storytellerRow = StorytellerRowView(context)
storytellerRowView.cellType = StorytellerListViewCellType.ROUND
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"/>
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()
The StorytellerRowView
inherits from StorytellerListView
.
Attributes can also be applied in XML.
<?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"
android:id="@+id/storyRowView"
android:layout_width="match_parent"
android:layout_height="wrap_content" />
val storytellerRowView = StorytellerRowView(context)
val customTheme: UiTheme
//~~~ build customized theme UITheme ~~ //
storytellerRowView.theme = customTheme
view.addView(storytellerRowView)
The StorytellerGridView
inherits from StorytellerListView
.
<?xml version="1.0" encoding="utf-8"?>
<com.storyteller.ui.list.StorytellerGridView
xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
android:id="@+id/storyGridView"
android:layout_width="match_parent"
android:layout_height="wrap_content"
app:cellType="round" />
val storytellerGridView = StorytellerGridView(context)
val customTheme: UiTheme
//~~~ build customized theme UITheme ~~ //
storytellerGridView.theme = customTheme
view.addView(storytellerGridView)