Implementing StorytellerListViewDelegate Callbacks

A StorytellerListViewDelegate has methods for managing StorytellerRowView and StorytellerGridView Story events.

How to Use

You can implement these optional methods when responding to the StorytellerListViewDelegate protocol:

• onDataLoadStarted() - called when the network request to load data for all Stories has started
• onDataLoadComplete(success: Bool, error: Error?, dataCount: Int) - called when the data loading network request is complete
  • success - whether or not the request was successful
  • error - the HTTP error if the request was not successful
  • dataCount - the number of Stories loaded
• onPlayerDismissed() - called when any Story has been dismissed
• tileBecameVisible(contentIndex: Int) - called whenever a tile is visible in the list view

class DelegateObject : StorytellerListViewDelegate {
    
    func onDataLoadStarted() {
        // Action on start of data network requests
    }
    
    func onDataLoadComplete(success: Bool, error: Error?, dataCount: Int) {
        // Action on completion of data network requests
    }
    
    func onPlayerDismissed() {
        // Action on dismissal of player
    }

    func tileBecameVisible(contentIndex: Int) {
        // for example, report to an analytics library which data was seen by the user
    }
}

Once an instance of this has been created, you can then set it to the delegate property of your StorytellerRowView or StorytellerGridView as follows:

let storytellerRow = StorytellerRowView()
let delegate = DelegateObject()

storytellerRow.delegate = delegate
storytellerRow.reloadData()

Make sure reloadData() is called on StorytellerRowView or StorytellerGridView instance after assignment, otherwise the delegate methods onDataLoadStarted() and onDataLoadComplete() will not be called.

Error Handling

By using the callback function onDataLoadComplete and the data it provides, you can handle the current state of the StorytellerRowView appropriately in your app.

Note: dataCount is the total number of Stories in the existing StorytellerRowView at any given time

Example:

    ...
    func onDataLoadComplete(success: Bool, error: Error?, dataCount: Int) {
        if success {
            // stories data has been loaded successfully
            // dataCount is the current total number of content, including newly added/removed data
        } else if let newError = error {
            // an error has occurred, use the unwrapped value `newError` for more information
            // dataCount is the total number of content before loading began
        }
    }

Another example:

    ...
    func onDataLoadComplete(success: Bool, error: Error?, dataCount: Int) {
        if let newError = error && dataCount == 0 {
            // content have failed to load with error and there is no data to show
            // you may wish to hide the `StorytellerRowView` instance here
            storytellerRowView.hidden = true
            storytellerRowViewHeightConstraint.constant = 0
        } 
    }

Tile Visibility

The callback tileBecameVisible is called whenever a tile is visible. This could be useful, for example, to integrate with an analytics library on the integrating app side. The callback passes a single contentIndex parameter which starts counting at 1 and is the index of the current tile in the carousel.

Example:

    func tileBecameVisible(contentIndex: Int) {
        // for example, report to an analytics library which content was seen by the user
    }