feat: Added new docs

2021-06-23 12:38:18 +05:30
parent 6d17472d07
commit c75a0388bb
29 changed files with 99 additions and 8 deletions
@@ -4,15 +4,11 @@ id: introduction
 sidebar_position: 1
 title: Introduction To Stream Chat For Flutter
 ---
+Exploring The Basics Of Stream Chat

 ![](../assets/sdk_title.png)

-Stream Chat allows you to build real-time chat messaging in less time.
-Rapidly ship in-app messaging with our highly reliable chat infrastructure and feature-rich SDKs.
-Drive in-app conversion, engagement, and retention.
-
-The Flutter SDK enables you to build any type of chat or messaging experience for Android, iOS, Web
-and Desktop.
+Stream Chat is a service that helps you easily build a full chat experience in your Flutter (and more) apps.

 This section of the documentation focuses on our Flutter SDK which helps you easily
 ship high quality messaging experiences in apps and programs built with the [Flutter toolkit made
@@ -37,12 +33,34 @@ We recommend building prototypes using the full UI package since it contains UI
 integrated with Stream's API. [stream_chat_flutter](https://pub.dev/packages/stream_chat_flutter)
 is the fastest way to get up and running using Stream chat in your app.

+The Flutter SDK enables you to build any type of chat or messaging experience for Android, iOS, Web
+and Desktop.
+
 If you're building a very custom UI and would prefer a more lean package,
 our core package will be suited to this use case. Core allows you to build custom,
 expressive UIs while retaining the benefits of our full Flutter SDK.
 APIs for accessing and controlling users, sending messages, etc are seamlessly integrated into
 this package and accessible via providers and builders.

+Before going into the docs, let's take a small detour to look at how the elements of Stream Chat are structured.
+
+There are two core elements in chat, <b>Users and Channels.</b>
+Channels are groups of one or more users that can message each other.
+In an app, you need to have a user connected to query channels.
+
+There is no specific distinction between a chat between two people and a group chat,
+but there is a way to create a unique chat between a certain number of people by creating a <b>distinct</b> channel.
+
+![](../assets/chat_basics.png)
+
+In essence, a normal two-person chat would be a <b>distinct channel</b> created with two members (you cannot add or delete members in this channel), whereas a group created with two people would simply be a <b>non distinct channel</b> (possible to add or remove members).
+
+Note: It is also possible to add more than two people in a distinct channel which retains the same add/removal properties and resembles the Slack DMs where you can DM two or more people as well.
+
+In summary, if you were creating a Whatsapp-like app, the first screen would be a <b>list of channels</b> - which on opening would show a <b>list of messages</b> that were sent by the users in the Channel.
+
+While this is a simplistic overview of the service, thankfully the Flutter SDK handles the UI and more time consuming things (media upload, offline storage, theming, etc.) for us.
+
 Before reading the docs, consider trying our [online API tour](https://getstream.io/chat/get_started/),
 it is a nice way to learn how the API works.
 It's in-browser so Javascript-based but the ideas are pretty much the same as Dart.
@@ -4,6 +4,8 @@ sidebar_position: 10
 title: Channel Members
 ---

+Manipulating Members In A Channel
+
 ### Adding & Removing Channel Members

 Using the addMembers() method adds the given users as members, while removeMembers() removes them.
@@ -4,6 +4,8 @@ sidebar_position: 6
 title: Creating Channels
 ---

+Create Channels In Your App
+
 Both channel <b>channel.query</b> and  <b>channel.watch</b> methods ensure that a channel exists and create one otherwise.
 If all you need is to ensure that a channel exists, you can use <b>channel.create</b>.
 Typically you use <b>channel.watch</b> client side and <b>channel.create</b> for a server side integration.
@@ -4,6 +4,8 @@ sidebar_position: 13
 title: Deleting And Hiding A Channel
 ---

+Remove Channels By Deleting Or Hiding
+
 ### Deleting a Channel

 You can delete a Channel using the delete method. This marks the channel as deleted and hides all the content.
@@ -4,6 +4,8 @@ sidebar_position: 25
 title: Events
 ---

+Understand Low Level Messaging Events
+
 Events allow the client to stay up to date with changes to the chat. Examples are a new message, a user's image that updated, a reaction, or a member joining the channel. There are a 4 different type of events. These first 2 types of events you receive if you're connected to Stream, no further action is needed to receive these events:

 Client events: You always receive these events.
@@ -3,6 +3,7 @@ id: introduction
 sidebar_position: 1
 title: Introduction
 ---
+Exploring the Basics of the stream_chat package (LLC)

 <h2> Official Dart Client for Stream Chat </h2>

@@ -4,6 +4,8 @@ sidebar_position: 11
 title: Invites
 ---

+Invite A User To Join A Channel
+
 ### Inviting Users

 Stream Chat provides the ability to invite users to a channel via the `channel` method with the `invites` array.
@@ -4,6 +4,8 @@ sidebar_position: 16
 title: Messages
 ---

+Send, Update And Delete Messages
+
 Let's dive right into it, the example below shows how to send a simple message using Stream:

 ```dart
@@ -4,6 +4,8 @@ sidebar_position: 23
 title: Moderation Tools
 ---

+Moderation Tools For A Better Chat Experience
+
 ### Flag

 Any user is allowed to flag a message.
@@ -4,6 +4,8 @@ sidebar_position: 12
 title: Muting Channels
 ---

+Muting Channels For Users
+
 Messages added to a channel will not trigger push notifications, nor change the unread count for the users that muted it.

 By default, mutes stay in place indefinitely until the user removes it; however, you can optionally set an expiration time.
@@ -4,6 +4,8 @@ sidebar_position: 15
 title: Channel Pagination
 ---

+Understanding Pagination For The Channel List
+
 The channel query endpoint allows you to paginate the list of messages, watchers, and members for one channel.
 To make sure that you are able to retrieve a consistent list of messages, pagination does not work with simple offset/limit parameters but instead,
 it relies on passing the ID of the messages from the previous page.
@@ -4,6 +4,8 @@ sidebar_position: 22
 title: Pinned Messages
 ---

+Pinning A Message In A Channel
+
 Pinned messages allow users to highlight important messages, make announcements, or temporarily promote content.
 Pinning a message is, by default, restricted to certain user roles, but this is flexible.
 Each channel can have multiple pinned messages and these can be created or updated with or without an expiration.
@@ -4,6 +4,8 @@ sidebar_position: 7
 title: Querying Channels
 ---

+More About Fetching A List Of Channels
+
 If you’re building a similar application to Facebook Messenger or Intercom, you’ll want to show a list of Channels.
 The Chat API supports MongoDB style queries to make this easy to implement.

@@ -3,6 +3,7 @@ id: querying_users
 sidebar_position: 4
 title: Querying Users
 ---
+Querying Users Across Channels

 The Query Users method allows you to search for users and see if they are online/offline.
 The example below shows how you can retrieve the details for 3 users in one API call:
@@ -4,6 +4,8 @@ sidebar_position: 18
 title: Reactions
 ---

+Adding And Removing User Reactions
+
 Stream Chat has built-in support for user Reactions. Common examples are likes, comments, loves, etc. Reactions can be customized so that you are able to use any type of reaction your application requires.


@@ -4,6 +4,8 @@ sidebar_position: 20
 title: Searching Messages
 ---

+Searching For Messages Across Channels
+
 Message search is built-in to the chat API. You can enable and/or disable the search indexing on a per channel type.
 The command shown below selects the channels in which John is a member.
 Next, it searches the messages in those channels for the keyword “'supercalifragilisticexpialidocious'”:
@@ -4,3 +4,4 @@ sidebar_position: 2
 title: Setup
 ---

+Understanding Setup
@@ -4,6 +4,8 @@ sidebar_position: 21
 title: Silent Messages
 ---

+Pushing Silent Messages
+
 Sometimes you want to add system or transactional messages to channels such as: "your ride is waiting for you",
 "James updated the information for the trip", "You and Jane are now matched" and so on.

@@ -4,6 +4,8 @@ sidebar_position: 14
 title: Slow Mode
 ---

+Using Slow Mode For Reduced Message Traffic
+
 Slow mode helps reduce noise on a channel by limiting users to a maximum of 1 message per cooldown interval.

 The cooldown interval is configurable and can be anything between 1 and 120 seconds. For instance, if you enable slow mode and set the cooldown interval to 30 seconds a user will be able to post at most 1 message every 30 seconds.
@@ -4,6 +4,8 @@ sidebar_position: 19
 title: Threads And Replies
 ---

+Creating And Paginating Threads
+
 Threads and replies provide your users with a way to go into more detail about a specific topic.

 This can be very helpful to keep the conversation organized and reduce noise.
@@ -4,6 +4,8 @@ sidebar_position: 24
 title: Typing Indicators
 ---

+Adding Typing Indicators To Your App
+
 All official SDKs support typing events out of the box and are handled on all channels with the typing_events featured enabled.
 Typing indicators allow you to show to users who is currently typing in the channel.
 This feature can be switched on/off on a channel-type basis using the CLI or directly from the Dashboard.
@@ -4,6 +4,8 @@ sidebar_position: 9
 title: Updating Channels
 ---

+Exploring Multiple Ways To Update A Channel
+
 There are two ways to update a channel using the Stream API - a partial or full update.
 A partial update will retain any custom key-value data, whereas a complete update is going to remove any that are unspecified in the API request.

@@ -4,6 +4,8 @@ sidebar_position: 17
 title: Uploading Files
 ---

+Uploading Files And Using A Custom CDN
+
 The `channel.sendImage` and `channel.sendFile` methods make it easy to upload files.

 This functionality defaults to using the Stream CDN. If you would like, you can easily change the logic to upload to your own CDN of choice.
@@ -4,6 +4,8 @@ sidebar_position: 5
 title: User Presence
 ---

+Check If A User Is Online / Check Last Active
+
 User presence allows you to show when a user was last active and if they are online right now.
 Whenever you read a user the data will look like this:

@@ -4,3 +4,4 @@ sidebar_position: 3
 title: User Types
 ---

+Diving Into User Types
@@ -4,6 +4,8 @@ sidebar_position: 8
 title: Watching Channels
 ---

+More About Watching A Channel
+
 The call to channel.watch does a few different things in one API call:

 * It creates the channel if it doesn't exist yet (if this user has the right permissions to create a channel)
@@ -4,9 +4,24 @@ sidebar_position: 1
 title: Introduction
 ---

+Understanding The Core Package Of The Flutter SDK
+
 This package provides business logic to fetch common things required for integrating Stream Chat into your application.
 The core package allows more customisation and hence provides business logic but no UI components.
-Please use the stream_chat_flutter package for the full fledged suite of UI components or stream_chat for the low-level client.
+Please use the `stream_chat_flutter` package for the full fledged suite of UI components or `stream_chat` for the low-level client.
+
+### Background
+
+In the early days of the Flutter SDK, the SDK was only split into the LLC (`stream_chat`) and
+the UI package (`stream_chat_flutter`). With this you could use a fully built interface with the UI package
+or a fully custom interface with the LLC. However, we soon recognised the need for a third intermediary
+package which made tasks like building and modifying a list or channels or messages easy but without
+the complexity of using low level components. The Core package (`stream_chat_flutter_core`) is a manifestation
+of the same idea and allows you to build an interface with Stream Chat without having to deal with
+low level code and architecture as well as implementing your own theme and UI effortlessly.
+
+We will now explore the components of this intermediary package and understand how it helps you build
+the experience you want your users to have.

 The package primarily contains three types of classes:

@@ -18,6 +33,10 @@ The package primarily contains three types of classes:

 These components allow you to have the maximum and lower-level control of the queries being executed.

+In BLoCs, the basic functionalities - such as queries for messages, channels or queries - are bundled up
+and passed along down the tree. Using a BLoC allows you to either create your own way to fetch and
+build UIs or use an inbuilt Core widget to do the work such as queries, pagination, etc for you.
+
 The BLoCs we provide are:

 * ChannelsBloc
@@ -26,7 +45,13 @@ The BLoCs we provide are:

 ### Core Components

-Core components usually are an easy way to fetch data associated with Stream Chat which are decoupled from UI and often expose UI builders. Data fetching can be controlled with the controllers of the respective core components.
+Core components usually are an easy way to fetch data associated with Stream Chat.
+Core components use functions exposed by the respective BLoCs (the ChannelListCore uses the ChannelsBloc)
+and use the respective controllers for various operations. Unlike heavier components from the UI
+package, core components are decoupled from UI and they expose builders instead to help you build
+a fully custom interface.
+
+Data fetching can be controlled with the controllers of the respective core components.

 * ChannelListCore (Fetch a list of channels)
 * MessageListCore (Fetch a list of messages from a channel)
@@ -4,3 +4,5 @@ sidebar_position: 2
 title: Setup
 ---

+Understanding Setup
+