ArticlesBlock

A list of articles as a self-contained section: the whole catalogue, a publication's, an issue's.

The block owns its whole lifecycle: it loads on first display, shows placeholders while loading, paginates as the user scrolls, offers a retry on failure, reloads by itself when the connection comes back, collapses when there is nothing to show or no identified session, and keeps its pages while it is off screen. The caller supplies onEvent and, optionally, its presentation.

ArticlesBlock(
    title = "For you",
    onEvent = { event ->
        when (event) {
            is ArticlesBlockEvent.ItemClick -> {
                // The whole list, so the reader swipes from one article to the next.
                CGS.reader().open(activity, event.articles.map { it.id }, event.position.index)
            }

            is ArticlesBlockEvent.ItemAudioClick -> playArticle(event.article)
            is ArticlesBlockEvent.ItemMoreClick -> showOptions(event.article)
            ArticlesBlockEvent.HeaderActionClick -> openArticleList()
        }
    }
)

Data is loaded only while the block is displayed. No coroutine scope, state holder or ViewModel is required from the caller. Several blocks on the same screen that show the same content share a single request.

The block needs a androidx.lifecycle.ViewModelStoreOwner in scope. Any ComponentActivity, AppCompatActivity or fragment already is one — writing no ViewModel of your own changes nothing, since the store comes with the activity. Only a view tree that has no owner at all, such as a ComposeView in a window the host set up by hand, has none; the block then fails on its first composition with "No ViewModelStoreOwner was provided via LocalViewModelStoreOwner", which names nothing of this SDK. Supplying one is a line: CompositionLocalProvider(LocalViewModelStoreOwner provides owner) { ArticlesBlock(…) }.

The block then takes the retention of whichever owner it found — a NavBackStackEntry under Navigation-Compose, the activity or the fragment otherwise — and that choice is the caller's. Blocks under the same owner showing the same content share one request and its loaded pages, so an activity-wide owner has two different screens share them, and a refresh on one seen by the other; a per-destination owner does not.

With the default ArticlesLayout.list the block is a vertical list of full-width rows. Capped with limit it takes only the room of its rows and sits in the caller's scrolling column, the way the publication screen lists an issue's contents; uncapped, it scrolls and paginates on its own and must be given bounded height instead. ArticlesLayout.richHorizontal is a carousel, safe in a scrolling column capped or not.

Parameters

Throws