Skip to content

Handle view callbacks#

Each view has its own delegate for events from that view: loading its content and closing its player. StorytellerStoriesRowView, StorytellerStoriesGridView, StorytellerClipsRowView, and StorytellerClipsGridView use the list view delegate, typed IListViewDelegate. For events from every player, such as analytics, see Handle global callbacks.

StorytellerClipsPlayerView and StorytellerEmbeddedClipsPlayerView use the Clips player delegate, typed IStorytellerClipsPlayerDelegate, through the same delegate property. It adds a callback for the back button.

Set a view delegate#

Set the delegate property on the view you want to observe. Assigning a new object replaces the view's previous delegate.

const storyRow = new Storyteller.StorytellerStoriesRowView('stories-row-id');
storyRow.delegate = {
  // Add the callbacks you need, for example:
  onDataLoadComplete: (success, error, dataCount) => {
    if (!success) {
      console.error('Stories could not load.', error);
    }
  },
};

const clipPlayer = new Storyteller.StorytellerClipsPlayerView(
  'clips-player-id',
  { externalId: 'clip-external-id' }
);
clipPlayer.topLevelBackButtonEnabled = true;
clipPlayer.delegate = {
  onTopLevelBackTapped: () => {
    window.history.back();
  },
};

For the Clips player views' initialization, sizing, and back button, see Add a Clips player to a page.

Delegate callbacks#

All callbacks are optional.

onDataLoadStarted#

onDataLoadStarted?: () => void;

Called when the view starts loading its Stories or Clips.

onDataLoadComplete#

onDataLoadComplete?: (success: boolean, error: Error | null, dataCount: number) => void;

Called when the view finishes loading its content:

  • success: true when content loaded. false when the request failed or returned no Stories or Clips.
  • error: an Error when success is false, otherwise null. The SDK doesn't export its error classes, so check error.message.
  • dataCount: the number of Stories loaded, or the number of Clips in the first page. Later Clips pages load without calling onDataLoadStarted or onDataLoadComplete. A Clips player that shows one Clip reports 1.

onPlayerDismissed#

onPlayerDismissed?: () => void;

Called when a Story or Clips player opened from this view is dismissed.

Clips player delegate#

IStorytellerClipsPlayerDelegate has the same callbacks as IListViewDelegate, and adds onTopLevelBackTapped.

onTopLevelBackTapped#

onTopLevelBackTapped?: () => void;

Called when the user taps the back button at the top of a StorytellerClipsPlayerView or StorytellerEmbeddedClipsPlayerView whose topLevelBackButtonEnabled is true.

The back button doesn't call onPlayerDismissed. If you don't define onTopLevelBackTapped, the button calls window.history.back(). When topLevelBackButtonEnabled is false or not set, the button stays hidden and doesn't call onTopLevelBackTapped.

Delegate interfaces#

interface IListViewDelegate {
  onDataLoadStarted?: () => void;

  onDataLoadComplete?: (
    success: boolean,
    error: Error | null,
    dataCount: number
  ) => void;

  onPlayerDismissed?: () => void;
}

interface IStorytellerClipsPlayerDelegate extends IListViewDelegate {
  onTopLevelBackTapped?: () => void;
}

The Storyteller Web Showcase hides a feed module when onDataLoadComplete reports a failure or no content, in handleDataLoadComplete.