Configuring a StorytellerListView#

Note

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

For more details on the specific features available for Rows and Grids, please see StorytellerRowView and StorytellerGridView

Initialization#

Stories initialization#

const storyRow = new Storyteller.StorytellerStoriesRowView('stories-row-id'); // All categories
const storyRowWithCategories = new Storyteller.StorytellerStoriesRowView(
  'stories-row-id',
  ['category-1', 'category-2']
);

Clips initialization#

const clipsRow = new Storyteller.StorytellerClipsRowView(
  'clips-row-id',
  'clip-collection-id'
);

Configuration#

The ListConfiguration class is used to configure the Storyteller.StorytellerStoriesRowView, Storyteller.StorytellerStoriesGridView, Storyteller.StorytellerClipsRowView, and Storyteller.StorytellerClipsGridView classes.

Stories configuration#

JavaScriptTypeScript

const storyRow = new Storyteller.StorytellerStoriesRowView('stories-row-id');
storyRow.configuration = {
  basename: 'top-stories', // Needed if there are multiple lists on the same page
  categories: ['category1', 'category2', 'category3'], // Stories only
  cellType: Storyteller.CellType.round, // Only for `StorytellerStoriesRowView`
  displayLimit: 10,
  preload: true, // Stories only
  theme: customTheme,
  uiStyle: 'dark',
};

const storyRow = new Storyteller.StorytellerStoriesRowView('stories-row-id');
const storyRowConfiguration: IListConfiguration<'StorytellerStoriesRowView'> = {
  basename: 'top-stories', // Needed if there are multiple lists on the same page
  categories: ['category1', 'category2', 'category3'], // Stories only
  cellType: Storyteller.CellType.round, // Only for `StorytellerStoriesRowView`
  displayLimit: 10,
  preload: true, // Stories only
  theme: customTheme,
  uiStyle: 'dark',
};
storyRow.configuration = storyRowConfiguration;

Clips configuration#

JavaScriptTypeScript

const clipsRow = new Storyteller.StorytellerClipsRowView(
  'clips-row-id',
  'collection-id'
);
clipsRow.configuration = {
  basename: 'top-clips', // Needed if there are multiple lists with the same collection on the same page
  displayLimit: 10,
  theme: customTheme,
  uiStyle: 'dark',
};

const clipsRow = new Storyteller.StorytellerClipsRowView(
  'clips-row-id',
  'collection-id'
);
const clipsRowConfiguration: IListConfiguration<'StorytellerClipsRowView'> = {
  basename: 'top-clips', // Needed if there are multiple lists with the same collection on the same page
  displayLimit: 10,
  theme: customTheme,
  uiStyle: 'dark',
};
clipsRow.configuration = clipsRowConfiguration;

Learn more

See the documentation for StorytellerStoriesRowView and StorytellerClipsRowView and StorytellerStoriesGridView and StorytellerClipsGridView for attributes specific to those components.

basename#

Each Stories/Clips view is assigned a basename which corresponds to the first segment of the hash URL fragment. For example:

https://www.getstoryteller.com/#basename/[STORY_ID]
https://www.getstoryteller.com/#basename/[COLLECTION_ID]/[CLIP_ID]

By default, the basename value is stories (for Stories) or clips (for Clips). You can choose to override this using ListConfiguration , or you can set the data-base-url attribute of the container div:

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

If there is only one Stories/Clips view on a single page, setting the basename is optional. In this case, opening a Story will take the user to #stories/[STORY_ID], and #clips/[COLLECTION_ID]/[CLIP_ID] for Clips. However, if there are multiple views on the same page, each Stories/Clips view's basename will be derived from its categories/collection. If multiple views have the same categories/collection, then you'll need to override their basename, so that each view has a unique basename. If all views have different categories, there's no need to override the basename, but you might choose to do so for improved readability of the player URL.

categories (Stories only)#

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.

You can use the configuration object to dynamically update the categories of a Storyteller row:

storyRow.configuration = {
  categories: ['new-category-id-1', 'new-category-id-2'],
};

The category IDs can be copied from the Storyteller CMS.

Learn more

See Categories for more information about managing categories in the CMS.

collection (Clips only)#

When initializing a Clips view, a collection ID is required:

const clipsRow = new Storyteller.StorytellerClipsRowView(
  'clips-row-id',
  'clip-collection-id'
);

Once a Clips view has been initialized, you can update its collection by using the configuration object:

clipsRow.configuration = {
  collection: 'new-clip-collection-id',
};

The collection ID can be copied from the Storyteller CMS.

Learn more

See Creating Collections for more information about managing collections in the CMS.

displayLimit#

The displayLimit is the maximum amount of tiles that can be shown in the list (optional).

preload#

Set preload to true to start loading the player before the user opens a Story. This will improve the user experience but will impact performance scores as the page will load additional scripts before they're needed.

theme#

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 customTheme = new Storyteller.UiTheme({
  light: {
    lists: {
      row: {
        startInset: 0,
        endInset: 0,
      },
    },
  },
});

uiStyle#

The uiStyle adjusts whether Storyteller renders in light mode, dark mode, or follows the system setting.

uiStyle takes the following values:

auto - default value, the List View will adjust its color scheme automatically according to the current system UI mode
light - force the List View to use the light theme
dark - force the List View to use the dark theme

The uiStyle can also be set on the container div using the data-ui-style attribute:

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

Methods#

reloadData#

reloadData();

The reloadData method starts loading fresh data for all Stories (or Clips) from the API. On completion, it updates the Story/Clip data, starts pre-fetching content and updates the read status of the Stories/Clips. The onDataLoadStarted and onDataLoadComplete delegate methods are called accordingly (the latter with appropriate data depending on the result of the API requests).

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

openStory, openStoryByExternalId, openPage, openCollection, openClipByExternalId#

The openStory, openStoryByExternalId, openPage, openCollection, and openClipByExternalId methods have been moved to the main Storyteller instance.

Learn more

See Additional Methods for more information.