Skip to content

Commit 6b3a33d

Browse files
dhyash-simformdhyash-simform
committed
docs: 📝 Updated Documentation
1 parent 11ade96 commit 6b3a33d

File tree

4 files changed

+871
-249
lines changed

4 files changed

+871
-249
lines changed

‎README.md‎

Lines changed: 25 additions & 235 deletions
Original file line numberDiff line numberDiff line change
@@ -6,259 +6,49 @@
66
package providing seamless integration with Database & Storage for your flutter chat app.
77

88
_Check out other amazing
9-
open-source [Flutter libraries](https://pub.dev/publishers/simform.com/packages)
9+
open-source [Flutter libraries](https://simform-flutter-packages.web.app)
1010
and [Mobile libraries](https://github.com/SimformSolutionsPvtLtd/Awesome-Mobile-Libraries) developed
1111
by Simform Solutions!_
1212

13-
## ✨ Key Features
13+
## Preview
1414

15-
- **Easy Setup:** Integrate [`chatview`][chatViewPackage] with your cloud service in 3 steps —> set
16-
the **Service Type** -> set **User ID** -> get **`ChatManager`**
17-
and use it with [`chatview`][chatViewPackage].
18-
- Supports **one-on-one and group chats** with **media uploads** *(audio not supported).*
15+
<img alt="The example app running in iOS" src="https://raw.githubusercontent.com/SimformSolutionsPvtLtd/flutter_chatview/main/preview/chatview.gif" width="300"/>
16+
17+
## Features
18+
19+
- **Easy Setup:** Integrate with [`chatview`][chatViewPackage] in 3 steps:
20+
1. Initialize the package by specifying **Cloud Service** (e.g., Firebase).
21+
2. Set the current **User ID**.
22+
3. Get **`ChatManager`** and use it with [`chatview`][chatViewPackage]
23+
- Supports **one-on-one** and **group chats** with **media uploads** *(audio not supported).*
1924

2025
***Note:*** *Currently, it supports only Firebase Cloud Services. Support for additional cloud
2126
services will be included in future releases.*
2227

23-
## 🎞️ Preview
28+
## Documentation
2429

25-
<img alt="The example app running in iOS" src="https://raw.githubusercontent.com/SimformSolutionsPvtLtd/flutter_chatview/main/preview/chatview.gif" width="300"/>
26-
27-
## 🚀 Getting Started
30+
Visit our [documentation](https://simform-flutter-packages.web.app/chatViewConnect) site for
31+
all implementation details, usage instructions, code examples, advanced features, database &
32+
storage structure and rules.
2833

29-
Add dependency to `pubspec.yaml`:
34+
## Installation
3035

3136
```yaml
3237
dependencies:
3338
chatview_connect: <latest-version>
3439
```
3540
36-
## 🔧 Setup
37-
38-
- **Firebase Integration:** Set up a [Firebase](https://firebase.google.com/) project (if you
39-
haven’t) and connect it to your Flutter app
40-
using [this guide](https://firebase.google.com/docs/flutter/setup?platform=android).
41-
42-
- Initialize `chatview_connect` just after the firebase initialization, specify your
43-
desired cloud service for use with [`chatview`][chatViewPackage].
44-
45-
```dart
46-
ChatViewConnect(ChatViewCloudService.firebase);
47-
````
48-
49-
- Set Current User:
50-
```dart
51-
ChatViewConnect.instance.setCurrentUserId('current_user_id');
52-
````
53-
54-
## 🏗 Using with [ChatView][chatViewPackage]
55-
56-
The `ChatController` from [`chatview`][chatViewPackage] has been replaced by `ChatManager`. It can
57-
be used for both **existing** and **new chat rooms**, depending on the parameters
58-
provided. [see full example here.](https://github.com/SimformSolutionsPvtLtd/chatview_connect/blob/master/example/lib/main.dart)
59-
60-
**Before:**
61-
62-
```dart
63-
ChatController _chatController = ChatController(
64-
initialMessageList: [...],
65-
scrollController: ScrollController(),
66-
currentUser: const ChatUser(...),
67-
otherUsers: const [...],
68-
);
69-
````
70-
71-
**After:**
72-
73-
- Simply specify the `chatRoomId`, and it will automatically fetch the participants and return the
74-
corresponding `ChatManager`.
75-
76-
````dart
77-
ChatManager _chatController = await ChatViewConnect.instance.getChatManager(
78-
// You can get `chatRoomId` from `createChat`, `createGroupChat`, or `getChats`
79-
chatRoomId: 'chat_room_id',
80-
scrollController: ScrollController(),
81-
config: ChatControllerConfig(syncOtherUsersInfo: true),
82-
);
83-
````
84-
85-
`ChatManager` internally manages various chat operations, when the corresponding methods are
86-
specified in the [`chatview`][chatViewPackage] widget.
87-
88-
```dart
89-
90-
@override
91-
Widget build(BuildContext context) {
92-
// ...
93-
child: ChatView(
94-
chatController: _chatController,
95-
// Sending messages and uploading media (image, or custom)
96-
// audio files are not uploaded, as network audio is not compatible with `chatview`.
97-
onSendTap: _chatController.onSendTap,
98-
sendMessageConfig: SendMessageConfiguration(
99-
textFieldConfig: TextFieldConfiguration(
100-
// Managing typing indicators
101-
// Note: automatic for one-to-one chats, manual for groups chats
102-
onMessageTyping: _chatController.onMessageTyping,
103-
),
104-
),
105-
chatBubbleConfig: ChatBubbleConfiguration(
106-
inComingChatBubbleConfig: ChatBubble(
107-
// Tracking message read status
108-
onMessageRead: (message) => _chatController.onMessageRead(
109-
message.copyWith(status: MessageStatus.read),
110-
),
111-
),
112-
),
113-
// Unsending messages
114-
replyPopupConfig: ReplyPopupConfiguration(
115-
onUnsendTap: _chatController.onUnsendTap,
116-
),
117-
// Updating reactions
118-
reactionPopupConfig: ReactionPopupConfiguration(
119-
userReactionCallback: _chatController.userReactionCallback,
120-
),
121-
),
122-
// ...
123-
}
124-
````
125-
126-
#### 🛠️ Additional Chat Room Methods:
127-
128-
| Method | Description | Return Type |
129-
|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------|
130-
| onSendTapFromMessage | Sends a message in the active chat room using an existing `Message` instance. | `Future<Message?>` |
131-
| updateGroupChat | Updates the specified attributes of a group chat. Any provided fields, such as `groupName` or `groupProfilePic`, will be updated accordingly. | `Future<bool>` |
132-
| addUserInGroup | Adds a new user to the current group chat. You can assign a role and choose whether to include previous chat history, as well as you can specify the start date from which the user should have access to the chat history. | `Future<bool>` |
133-
| removeUserFromGroup | Removes a specified user from the current group chat. ***Note:*** If the last member is removed, the all chat data will be deleted. | `Future<bool>` |
134-
| leaveFromGroup | Allows the current user to exit the group chat. ***Note:*** If the current user is the last remaining member, all chat data will be deleted. | `Future<bool>` |
135-
| dispose | When leaving the chat room, make sure to dispose of the connection to stop listening to messages, user activity, and chat room metadata streams. | `void` |
136-
137-
#### 🛠️ Chats Methods:
138-
139-
- To use chat methods that are not specific to a particular chat room, obtain the `ChatManager`
140-
using the method below. **Note:** This instance does not support chat room-specific methods.
141-
142-
```dart
143-
ChatManager _chatController = ChatViewConnect.instance.getChatManager();
144-
145-
@override
146-
Widget build(BuildContext context) {
147-
return Scaffold(
148-
body: child: StreamBuilder<List<ChatRoom>>(
149-
stream: _chatController.getChats(),
150-
builder: (context, snapshot) {
151-
// ...
152-
},
153-
),
154-
);
155-
}
156-
157-
````
158-
159-
| Method | Description | Return Type |
160-
|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------|
161-
| getUsers | Retrieves a map of user IDs and their corresponding `ChatUser` details. | `Future<Map<String, ChatUser>>` |
162-
| getChats | Returns a real-time stream of chat rooms list, including details such as chat room ID, participants, last message, and unread message count. | `Stream<List<ChatRoom>>` |
163-
| createChat | Creates a one-to-one chat room by specifying the other user's ID and it returns the `chatRoomID`. | `Future<String?>` |
164-
| createGroupChat | Creates a group chat by providing a group name, an optional profile picture, and a list of participants with their assigned roles and it returns the `chatRoomID`. | `Future<String?>` |
165-
| deleteChat | Deletes a chat room by its ID, removing it from the database, all users' chat lists, and deleting associated media from storage. | `Future<bool>` |
166-
| updateUserActiveStatus | Updates a user’s activity status by passing the desired state (e.g., online or offline). | `Future<bool>` |
167-
| resetCurrentUserId | Resets the current user ID | `void` |
168-
169-
## 💾 Database & Storage Documents
170-
171-
| Document | Link |
172-
|----------------------------|--------------------------------------------------------------------------------|
173-
| Firestore Database Schema | [Click here to view the schema](doc/firebase/firebase-database-schema.md) |
174-
| Firebase Storage Structure | [Click here to view the structure](doc/firebase/firebase-storage-structure.md) |
175-
176-
## 🔒 Firebase Security Rules
177-
178-
These Firebase Security Rules define access control
179-
for both the [Firestore Database](https://firebase.google.com/docs/firestore/security/get-started)
180-
and [Firebase Storage](https://firebase.google.com/docs/storage/security), ensuring secure data
181-
handling and media uploads in a chat applications using `chatview_connect`. The rules
182-
enforce authentication, user permissions, and chat room membership validation to maintain secure
183-
access.
184-
185-
Copy and paste the rules into your project's Firebase console under the Firestore Rules tab. For
186-
more information, visit the [Firebase Security Rules](https://firebase.google.com/docs/rules)
187-
documentation.
188-
189-
| Rules | Link |
190-
|--------------------|-----------------------------------------------------------------------------|
191-
| Firestore Database | [Click here to view the rules](doc/firebase/rules/firestore-security-rules) |
192-
| Firebase Storage | [Click here to view the rules](doc/firebase/rules/storage-security-rules) |
193-
194-
## ⚙️ Optional Configuration
195-
196-
#### Properties of `ChatViewConnect`:
197-
198-
- `chatUserConfig`: Use this if your user collection documents have field keys that differ from
199-
those in the default `ChatUser` model.
200-
201-
```dart
202-
ChatViewConnect(
203-
ChatViewCloudService.firebase,
204-
chatUserModelConfig: const ChatUserModelConfig(
205-
idKey: 'user_id',
206-
nameKey: 'first_name',
207-
profilePhotoKey: 'avatar',
208-
),
209-
);
210-
````
211-
212-
- `cloudServiceConfig`: This parameter allows you to specify a cloud configuration based on the
213-
selected database type.
214-
215-
**Firebase**: Use the `FirebaseCloudConfig` class, which provides the following
216-
parameters:
217-
218-
- **`databasePathConfig`**: Use this if your user collection is not located at the top level in
219-
Firestore.
220-
221-
- **`collectionNameConfig`**: Use this if your user collection names differs from the
222-
default.
223-
224-
```dart
225-
ChatViewConnect(
226-
ChatViewCloudService.firebase,
227-
cloudServiceConfig: FirebaseCloudConfig(
228-
databasePathConfig: FirestoreChatDatabasePathConfig(
229-
// If your users collection is inside `organizations/simform/users`.
230-
userCollectionPath: 'organizations/simform',
231-
),
232-
collectionNameConfig: FirestoreChatCollectionNameConfig(
233-
// If your user collection is named `simform_users`.
234-
users: 'simform_users',
235-
...,
236-
),
237-
),
238-
);
239-
````
240-
241-
#### Properties of `ChatControllerConfig`:
242-
243-
| Properties | Description |
244-
|---------------------------------|-------------------------------------------------------------------------------------------|
245-
| syncOtherUsersInfo | Whether to sync other users' information like Username, Profile Picture, Online/Offline. |
246-
| onUsersActivityChange | Callback triggered when users' Membership Status, Typing Status, Activity Status changes. |
247-
| chatRoomMetadata | Callback to receive chat room participants' details. |
248-
| onChatRoomDisplayMetadataChange | Callback triggered when chat name, chat profile picture changes. |
249-
250-
## 👥 Main Contributors
41+
## Support
25142
252-
<table>
253-
<tr>
254-
<td align="center"><a href="https://github.com/yash-dhrangdhariya"><img src="https://avatars.githubusercontent.com/u/72062416?v=4" width="100px;" alt=""/><br /><sub><b>Yash Dhrangdhariya</b></sub></a></td>
255-
<td align="center"><a href="https://github.com/aditya-chavda"><img src="https://avatars.githubusercontent.com/u/41247722?v=4" width="100px;" alt=""/><br /><sub><b>Aditya Chavda</b></sub></a></td>
256-
<td align="center"><a href="https://github.com/vatsaltanna"><img src="https://avatars.githubusercontent.com/u/25323183?s=100" width="100px;" alt=""/><br /><sub><b>Vatsal Tanna</b></sub></a></td>
257-
</tr>
258-
</table>
43+
For questions, issues, or feature
44+
requests, [create an issue](https://github.com/SimformSolutionsPvtLtd/chatview_connect/issues)
45+
on GitHub or reach out via the GitHub Discussions tab. We're happy to help and encourage community
46+
contributions.
47+
To contribute documentation updates specifically, please make changes to the `doc/documentation.md`
48+
file and submit a pull request.
25949

260-
## 📜 License
50+
## License
26151

262-
[MIT](LICENSE)
52+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
26353

26454
[chatViewPackage]: https://pub.dev/packages/chatview

0 commit comments

Comments
 (0)