Configuring a StorytellerListView

Table of Contents

1. Attributes
2. Methods
3. StorytellerRowView
4. StorytellerGridView

StorytellerListViewDelegate has methods for managing StorytellerRowView and StorytellerGridView events. Please see the dedicated StorytellerDelegate for handling other events.

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.

Attributes

The StorytellerRowView and StorytellerGridView can be customized using these attributes:

cellType

Example:

storytellerRow.cellType = "square"

The cellType is the style of the cell. This can either be round or square. The default value is square.

delegate

Example:

class foo: StorytellerListViewDelegate {

	let storytellerRow = StorytellerRowView()

	init() {
		super.init()
		storytellerRow.delegate = self
	}
}

The delegate is the StorytellerListViewDelegate instance for StorytellerListView callbacks. For more information, see Implementing StorytellerListViewDelegate methods.

categories

Example:

storytellerRow.categories = ["test_category"]

The categories attribute assigns a list of Story Categories to be displayed inside a row.

theme

Example:

let theme = UITheme()
//here do all customizations to theme object
storytellerRow.theme = theme

The theme attribute is the theming style used to render Story items in list and activities launched from this list. If you do not set a theme, then Storyteller.theme global attribute is used. For more details, see the dedicated Themes page.

uiStyle

Example:

storytellerRow.uiStyle = .auto

The uiStyle sets whether Storyteller should be rendered in light or dark mode. It can be set to auto, light, or dark. The default value is auto.

displayLimit

Example:

storytellerRow.displayLimit = 5

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

StorytellerListViewCellType

The StorytellerListViewCellType enum can be used to set the cellType property in a StorytellerRowView or StorytellerGridView, the property can also be set as a plain string matching the values round or square

    let storytellerRow = StorytellerRowView()
    storytellerRow.cellType = StorytellerListViewCellType.round.rawValue

StorytellerListViewStyle

The uiStyle property can be used to set the overall color schemes, suitable for dark or light modes. This is optional and can be adjusted for additional UI mode control.

• StorytellerListViewStyle.auto - default value, the SDK will adjust its color scheme automatically according to the current system UI mode
• StorytellerListViewStyle.light - force the SDK to use the light theme
• StorytellerListViewStyle.dark - force the SDK to use the dark theme

Using in Dynamic Containers

If you are using in StorytellerRowView or StorytellerGridView remember to attach prepareForReuse to UITableViewCell lifecycle

override func prepareForReuse() {
    super.prepareForReuse()
    storytellerRow.prepareForReuse()
}

Categories

The categories property assigns a list of Categories to be displayed inside the row/grid. Categories can be defined in the CMS. See the Categories section of the User Guide for more information.

let storytellerRow = StorytellerRowView()
storytellerRow.categories = ["<category-id-1>", "<category-id-2>"]

Methods

reloadData

reloadData()

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).

let storytellerRow = StorytellerRowView()
storytellerRow.reloadData()

For more information on how to use reloadData, see the dedicated StorytellerListViewDelegate page.

---

StorytellerRowView

The StorytellerRowView inherits from StorytellerListView. This section is for attributes that can be only used on a StorytellerRowView.

Using in Dynamic Containers

To use StorytellerRowView in dynamic container like UITableView section header, please set desired rowHeight and allow UITableView to use autosizing:

   tableView.sectionHeaderHeight = UITableView.automaticDimension

   // Can be anything greater than zero.
   tableView.estimatedSectionHeaderHeight = 1

then implement UITableViewDelegate methods:

   override func tableView(_ tableView: UITableView, viewForHeaderInSection section: Int) -> UIView? {
      storytellerRowView = StorytellerRowView()
      return storytellerRowView
   }

   override func tableView(_ tableView: UITableView, heightForHeaderInSection section: Int) -> CGFloat {
      return UITableView.automaticDimension
   }

---

StorytellerGridView

The StorytellerGridView inherits from StorytellerListView. This section is for attributes that can be only used on a StorytellerGridView.

Attributes

StorytellerGridView specific attributes:

• gridDelegate - the StorytellerGridViewDelegate instance for StorytellerGridView callbacks

Methods

reloadData

func reloadData(cell: UITableViewCell, tableView: UITableView)

When using StorytellerGridView inside UITableViewCell then the number of Stories influences the height of the grid hence overall height of the UITableViewCell. During reusing cell it is required to pass cell and tableView to adjust it height outside from StorytellerGridView.

func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
    guard let cell = tableView.dequeueReusableCell(
        withIdentifier: StorytellerTableViewCell.defaultCellReuseIdentifier,
        for: indexPath) as? StorytellerTableViewCell
    else {
        fatalError("Proper cell was not found in UITableView")
    }

    cell.reloadData(cell: cell, tableView: tableView)

    return cell
}

GridDelegate

A StorytellerGridViewDelegate has methods for managing StorytellerGridView events.

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

• contentSizeDidChange - this method is called when the size of the grid changes. This can occur after calling reloadData when new Stories are fetched from the server or when a user's device is rotated.

class StorytellerGridViewDelegateImplementation : StorytellerGridViewDelegate {

    func contentSizeDidChange(_ size: CGSize) {
        // calculated size of grid
    }
}

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

let storytellerGrid = StorytellerGridView()
let delegate = StorytellerGridViewDelegateImplementation()

storytellerGrid.gridDelegate = delegate
storytellerGrid.reloadData()