Storyteller List

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.

Properties

The StorytellerRowView can be customized using these properties:

• theme: the StorytellerUiTheme, used for customizing the appearance of the row.
• delegate: the StorytellerListDelegate instance for Storyteller List callbacks (see Implementing StorytellerListViewDelegate methods).

StorytellerListTheme

The theme property can be used to set the theme for a Storyteller List. Setting the theme for a list will override the values set in Storyteller.sharedInstance.theme.list, only for this list.

const storyRow = new Storyteller.RowView('row-id');
storyRow.theme = new Storyteller.UiTheme({
  light: {
    lists: {
      row: {
        startInset: 0,
        endInset: 0,
      }
    }
  }
});

Attributes

Storyteller Lists can also be customized using the following attributes:

These attributes can be set in 2 ways. It can be set on the container div, using the data-[ATTRIBUTE_NAME] attribute, with the attribute name converted to kebab case

<div id="storyteller-row" data-ui-style="dark"></div>

It can also be set programmatically after row initialization.

const storyRow = new Storyteller.RowView('storyteller-row');
storyRow.uiStyle = 'light';

See the documentation for RowView and Grid View for attributes specific to those components

Categories

You can optionally set a list of category IDs for each list view. This means only stories published in these categories will be displayed in this list. If no categories are supplied, stories published in the 'Home' list will be shown.

The category IDs can be copied from the Storyteller CMS. See Categories for more information about managing categories in the CMS.

const storyRow = new Storyteller.RowView('row-id', [
  'category-id-1',
  'category-id-2',
]);

Methods

openStory

openStory(id: string);

This method opens the player at the story with the specified id. If the story is not found, the first story is opened instead.

const storytellerRow = new Storyteller.RowView('story-row')

storytellerRow.openStory()            //Opens the first story
storytellerRow.openStory(id: "")      //Opens the first story
storytellerRow.openStory(id: <story-id>)  //Opens the story with id <story-id>, if that doesn't exist it then opens the first story

openPage

openPage(pageId: string, onError?: (message: string) => void);

This method opens the player at the page with the specified id. If the page is not found, then the onError callback will be called with an error message.

reloadData

reloadData();

The reloadData method starts loading fresh data for all stories from the API. On completion, it updates the story data, starts pre-fetching content and updates the read status of the stories. The onStoriesDataLoadStarted and onStoriesDataLoadComplete delegate methods are called accordingly (the latter with appropriate data depending on the result of the API requests).

const storyRow = new Storyteller.RowView('row-id');
storyRow.reloadData();

Configuring Multiple Lists

To allow multiple lists to be displayed on a single page, the data-base-url attribute must be set on the container divs. This attribute corresponds to the first segment of the hash url fragment and must be unique to each story list on a page.

<div id="first-story-row" data-base-url="story-row-1"></div>
<div id="second-story-row" data-base-url="story-row-2"></div>

Clicking on a story tile in the first row would direct a user to #story-row-1/{storyId} and clicking a tile in the second row would direct them to #story-row-2/{storyId}

The default value of data-base-url is stories, meaning it can be omitted when only one list is being displayed, or the base url of one list should be stories

<div id="first-story-row"></div>
<div id="second-story-row" data-base-url="more-stories"></div>