ListStore Guide: Adding a new list (WIP)

This guide is currently WIP and its contents might change significantly while the rest of the guide is fleshed out. If you have any questions/feedback, please reach out to @oguzkocer.

Table of Contents // TODO: Add links for each page

1. Introduction
2. Most important component: The ListDescriptor
3. How to consume an existing list
4. How to implement a new list
5. Sectioning (link added in consumption)
6. Consider this! (Common gotchas)
7. Internals

---

Before reading this guide, please make sure you have read both Introduction and Consuming a list pages. Even if you don't intend to implement the consumption part of a feature, it's still important to think about how something is going to be consumed before implementing the internals of it.

To add a new list to ListStore, we have quite a few things to implement, but by design these are all fairly simple. Here is a checklist you should copy into your issue and follow along:

You MUST implement the following:

• Implement a ListDescriptor as discussed in ListDescriptor page. You MUST implement a uniqueIdentifier and typeIdentifier for your ListDescriptor or a lot of weird things might happen. This is very important, so please ask for help if anything is not clear about it.
• Implement a way to fetch a list given a ListDescriptor and an offset. This will be necessary to consume a list in ListItemDataSourceInterface.fetchList
• When the list is fetched, dispatch FETCHED_LIST_ITEMS action. You'll need to pass the following parameters to this action: the ListDescriptor, remote item ids as List<Long>, whether you loaded more data (or fetched the first page) as boolean and if there is more data to be loaded as boolean. We might consider getting rid of this requirement in the future in favor of using a coroutine for fetching the list.
• Implement a way to fetch a single item. If you can implement a way to fetch a list of items (given their ids) that'd be even better. This will be necessary to consume a list in ListItemDataSourceInterface.getItemsAndFetchIfNecessary.

Good to have:

• If you need the UI to reload its data from the DB (and you need a central way to control this) use LIST_DATA_INVALIDATED action. An example would be when you fetch missing items from remote or downloaded the media of a post etc.
• When individual items are removed, use LIST_ITEMS_REMOVED action which will remove given ids from all the lists for that ListDescriptorTypeIdentifier
• If you need all the lists for a certain ListDescriptorTypeIdentifier to re-fetch their ids from network, use LIST_REQUIRES_REFRESH action. All active PagedListWrappers listen for this event and trigger fetchFirstPage if their ListDescriptorTypeIdentifier matches the action's.