From 2083c3d72aa89857355a3f2790dadc5297669834 Mon Sep 17 00:00:00 2001 From: Salvatore Giordano Date: Mon, 2 May 2022 11:26:57 +0200 Subject: [PATCH] StreamUserListController --- .../stream_channel_list_controller.mdx | 7 +- .../stream_user_list_controller.mdx | 110 ++++++++++++++++++ .../example/lib/main.dart | 7 +- 3 files changed, 122 insertions(+), 2 deletions(-) create mode 100644 docusaurus/docs/Flutter/stream_chat_flutter_core/stream_user_list_controller.mdx diff --git a/docusaurus/docs/Flutter/stream_chat_flutter_core/stream_channel_list_controller.mdx b/docusaurus/docs/Flutter/stream_chat_flutter_core/stream_channel_list_controller.mdx index e1aaaec4..310ee569 100644 --- a/docusaurus/docs/Flutter/stream_chat_flutter_core/stream_channel_list_controller.mdx +++ b/docusaurus/docs/Flutter/stream_chat_flutter_core/stream_channel_list_controller.mdx @@ -80,7 +80,12 @@ Widget build(BuildContext context) => Scaffold( itemBuilder: (BuildContext context, int index) { if (index == channels.length) { if (error != null) { - return Text(error.message); + return TextButton( + onPressed: () { + channelListController.retry(); + }, + child: Text(error.message), + ); } return CircularProgressIndicator(); } diff --git a/docusaurus/docs/Flutter/stream_chat_flutter_core/stream_user_list_controller.mdx b/docusaurus/docs/Flutter/stream_chat_flutter_core/stream_user_list_controller.mdx new file mode 100644 index 00000000..dc394416 --- /dev/null +++ b/docusaurus/docs/Flutter/stream_chat_flutter_core/stream_user_list_controller.mdx @@ -0,0 +1,110 @@ +--- +id: stream_user_list_controller +sidebar_position: 5 +title: StreamUserListController +--- + +A Widget For Controlling A List Of Users + +### Background + +The `StreamUserListController` is a controller class that allows you to control a list of users. +`StreamUserListController` is a required parameter of the `StreamUserListView` widget. +Check the [`StreamUserListView` documentation](../stream_chat_flutter/stream_user_list_view.mdx) to read more about that. + +### Basic Example + +Building a custom user list is a very common task. Here is an example of how to use the `StreamUserListController` to build a simple list with pagination. + +First of all we should create an instance of the `StreamUserListController` and provide it with the `StreamChatClient` instance. +You can also add a `Filter`, a list of `SortOption`s and other pagination-related parameters. + +```dart +class UserListPageState extends State { + /// Controller used for loading more data and controlling pagination in + /// [StreamUserListController]. + late final userListController = StreamUserListController( + client: StreamChatCore.of(context).client, + ); +``` + +Make sure you call `userListController.doInitialLoad()` to load the initial data and `userListController.dispose()` when the controller is no longer required. + +```dart +@override +void initState() { + userListController.doInitialLoad(); + super.initState(); +} + +@override +void dispose() { + userListController.dispose(); + super.dispose(); +} +``` + +The `StreamUserListController` is basically a [`PagedValueNotifier`](./paged_value_notifier.mdx) that notifies you when the list of users has changed. +You can use a [`PagedValueListenableBuilder`](./paged_value_listenable_builder.mdx) to build your UI depending on the latest users. + +```dart +@override +Widget build(BuildContext context) => Scaffold( + body: PagedValueListenableBuilder( + valueListenable: userListController, + builder: (context, value, child) { + return value.when( + (users, nextPageKey, error) => LazyLoadScrollView( + onEndOfPage: () async { + if (nextPageKey != null) { + userListController.loadMore(nextPageKey); + } + }, + child: ListView.builder( + /// We're using the users length when there are no more + /// pages to load and there are no errors with pagination. + /// In case we need to show a loading indicator or and error + /// tile we're increasing the count by 1. + itemCount: (nextPageKey != null || error != null) + ? users.length + 1 + : users.length, + itemBuilder: (BuildContext context, int index) { + if (index == users.length) { + if (error != null) { + return TextButton( + onPressed: () { + userListController.retry(); + }, + child: Text(error.message), + ); + } + return CircularProgressIndicator(); + } + + final _item = users[index]; + return ListTile( + title: Text(_item.name ?? ''), + ); + }, + ), + ), + loading: () => const Center( + child: SizedBox( + height: 100, + width: 100, + child: CircularProgressIndicator(), + ), + ), + error: (e) => Center( + child: Text( + 'Oh no, something went wrong. ' + 'Please check your config. $e', + ), + ), + ); + }, + ), + ); +``` + +In this case we're using the [`LazyLoadScrollView`](./lazy_load_scroll_view.mdx) widget to load more data when the user scrolls to the bottom of the list. \ No newline at end of file diff --git a/packages/stream_chat_flutter_core/example/lib/main.dart b/packages/stream_chat_flutter_core/example/lib/main.dart index 7f093c6d..379d26a1 100644 --- a/packages/stream_chat_flutter_core/example/lib/main.dart +++ b/packages/stream_chat_flutter_core/example/lib/main.dart @@ -127,7 +127,12 @@ class _HomeScreenState extends State { itemBuilder: (BuildContext context, int index) { if (index == channels.length) { if (error != null) { - return Text(error.message); + return TextButton( + onPressed: () { + channelListController.retry(); + }, + child: Text(error.message), + ); } return CircularProgressIndicator(); }