tsai
/
abp
mirror of https://github.com/abpframework/abp.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Expand Chat module documentation

pull/25826/head
maliming 2 months ago
parent
8e5595519a
commit
a2593a7e69
No known key found for this signature in database GPG Key ID: A646B9CB645ECEA4
1 changed files with 57 additions and 13 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 70
      docs/en/modules/chat.md

70
docs/en/modules/chat.md
View File

@ -36,7 +36,7 @@ If you modified your solution structure, adding module using ABP Suite might not
In order to do that, add packages listed below to matching project on your solution. For example, ```Volo.Chat.Application``` package to your **{ProjectName}.Application.csproj** like below; In order to do that, add packages listed below to matching project on your solution. For example, ```Volo.Chat.Application``` package to your **{ProjectName}.Application.csproj** like below;
```json ```xml
<PackageReference Include="Volo.Chat.Application" Version="x.x.x" /> <PackageReference Include="Volo.Chat.Application" Version="x.x.x" />
``` ```
@ -49,7 +49,7 @@ After adding the package reference, open the module class of the project (eg: `{
)] )]
``` ```
> If you are using Blazor Web App, you need to add the `Volo.Chat.Blazor.WebAssembly` package to the **{ProjectName}.Blazor.Client.csproj** project and ad the `Volo.Chat.Blazor.Server` package to the **{ProjectName}.Blazor.csproj** project. > If you are using Blazor Web App, you need to add the `Volo.Chat.Blazor.WebAssembly` package to the **{ProjectName}.Blazor.Client.csproj** project and add the `Volo.Chat.Blazor.Server` package to the **{ProjectName}.Blazor.csproj** project.
The `Volo.Chat.SignalR` package must be added according to your project structure: The `Volo.Chat.SignalR` package must be added according to your project structure:
@ -107,18 +107,38 @@ You can visit [Chat module package list page](https://abp.io/packages?moduleName
## User interface ## User interface
### Manage chat feature ### Chat feature and permissions
Chat module defines the chat feature, you need to enable the chat feature to use chat. The `Chat.Enable` feature is disabled by default. Enable it for a tenant or edition before granting chat permissions.
![chat-feature](../images/chat-feature.png) ![chat-feature](../images/chat-feature.png)
The module defines the following permissions:
* `Chat.Messaging`: Allows a user to open the chat page and exchange messages. A message can only be sent if the target user also has this permission.
* `Chat.Searching`: A child permission of `Chat.Messaging`. It allows a user to start a conversation with a user who is not already in the conversation history. Without this permission, the user can continue existing conversations.
* `Chat.SettingManagement`: Allows a user to manage the chat settings.
### Chat page ### Chat page
This is the page that users send messages to each other. This is the page that users send messages to each other.
![chat-page](../images/chat-page.png) ![chat-page](../images/chat-page.png)
Message text is required. By default, it must contain between 1 and 4,096 characters. The conversation API returns the newest messages first; the built-in user interfaces reverse that result to display messages in chronological order.
### Deleting messages and conversations
The following settings control deletion behavior:
| Setting | Default | Description |
| --- | --- | --- |
| `Volo.Chat.Messaging.DeletingMessages` | `Enabled` | `Enabled` allows deletion at any time, `Disabled` prevents deletion, and `EnabledWithDeletionPeriod` allows deletion only during the configured period after the message is created. |
| `Volo.Chat.Messaging.MessageDeletionPeriod` | `0` | Deletion period in seconds when message deletion is set to `EnabledWithDeletionPeriod`. |
| `Volo.Chat.Messaging.DeletingConversations` | `Enabled` | Enables conversation deletion. It is effective only when message deletion is set to `Enabled`. |
Deleting a message removes the shared message and both users' message records. Deleting a conversation removes both users' conversation records and all messages between them. These operations are shared deletions, not a "hide for me" operation. Deletion notifications are sent through the real-time channel.
### Chat icon on navigation bar ### Chat icon on navigation bar
An icon that shows unread message count of the user and leads to chat page when clicked is added to navigation menu. An icon that shows unread message count of the user and leads to chat page when clicked is added to navigation menu.
@ -213,9 +233,9 @@ See the [connection strings](../framework/fundamentals/connection-strings.md) do
#### Installation #### Installation
In order to configure the application to use the chat module, you first need to import `provideChatConfig` from `@volo/abp.ng.chat/config` to root application confiuration. Then, you will need to append it to the `appConfig` array. In order to configure the application to use the chat module, you first need to import `provideChatConfig` from `@volo/abp.ng.chat/config` to the root application configuration. Then, you will need to append it to the `providers` array.
```js ```ts
// app.config.ts // app.config.ts
import { provideChatConfig } from '@volo/abp.ng.chat/config'; import { provideChatConfig } from '@volo/abp.ng.chat/config';
@ -228,20 +248,24 @@ export const appConfig: ApplicationConfig = {
``` ```
The chat module should be imported and lazy-loaded in your routing array. It has a static `createRoutes` method for configuration. It is available for import from `@volo/abp.ng.chat`. The chat module should be imported and lazy-loaded in your routing array. It exports a `createRoutes` function from `@volo/abp.ng.chat`.
```js ```ts
// app.routes.ts // app.routes.ts
const APP_ROUTES: Routes = [ const APP_ROUTES: Routes = [
// ... // ...
{ {
path: 'chat', path: 'chat',
loadChildren: () => loadChildren: () =>
import('@volo/abp.ng.chat').then(c => c.createRoutes(/* options here */)), import('@volo/abp.ng.chat').then(c => c.createRoutes()),
}, },
]; ];
``` ```
#### Component replacement
The Angular chat route uses the `Chat.ChatComponent` replacement key and `ChatComponent` as its default component. See the [Angular component replacement documentation](../framework/ui/angular/component-replacement.md) if you need to replace the page.
#### Services / Models #### Services / Models
Chat module services and models are generated via `generate-proxy` command of the [ABP CLI](../cli). If you need the module's proxies, you can run the following command in the Angular project directory: Chat module services and models are generated via `generate-proxy` command of the [ABP CLI](../cli). If you need the module's proxies, you can run the following command in the Angular project directory:
@ -254,7 +278,7 @@ abp generate-proxy --module chat
The Chat module remote endpoint URLs can be configured in the environment files. The Chat module remote endpoint URLs can be configured in the environment files.
```js ```ts
export const environment = { export const environment = {
// other configurations // other configurations
apis: { apis: {
@ -274,12 +298,24 @@ The Chat module remote URL configurations shown above are optional.
> If you don't set the `signalRUrl`, `Chat.url` will be used as fallback. If you don't set the `Chat` property, the `default.url` will be used as fallback. > If you don't set the `signalRUrl`, `Chat.url` will be used as fallback. If you don't set the `Chat` property, the `default.url` will be used as fallback.
### Blazor WebAssembly UI ### Blazor and MAUI UIs
#### Remote Endpoint URL #### Remote Endpoint URL
The SignalR base URL can be configured with the option type that matches the UI package:
| UI package | Option type | Fallback when `SignalrUrl` is not set |
| --- | --- | --- |
| Blazor Server | `ChatBlazorServerOptions` | The current application URL. |
| Blazor WebAssembly | `ChatBlazorWebAssemblyOptions` | `AbpRemoteServiceOptions.RemoteServices.Default.BaseUrl`. |
| Blazor MAUI | `ChatBlazorMauiBlazorOptions` | `AbpRemoteServiceOptions.RemoteServices.Default.BaseUrl`. |
| MudBlazor Server | `ChatBlazorMudBlazorServerOptions` | The current application URL. |
| MudBlazor WebAssembly | `ChatBlazorMudBlazorWebAssemblyOptions` | `AbpRemoteServiceOptions.RemoteServices.Default.BaseUrl`. |
| MudBlazor MAUI | `ChatBlazorMudBlazorMauiBlazorOptions` | `AbpRemoteServiceOptions.RemoteServices.Default.BaseUrl`. |
The Chat module remote endpoint URLs can be configured via the `ChatBlazorWebAssemblyOptions`. The module appends the `/signalr-hubs/chat` path to the resolved base URL.
For example, the Chat module remote endpoint URL can be configured for Blazor WebAssembly via the `ChatBlazorWebAssemblyOptions`:
```csharp ```csharp
Configure<ChatBlazorWebAssemblyOptions>(options => Configure<ChatBlazorWebAssemblyOptions>(options =>
@ -303,4 +339,12 @@ Configure<ChatBlazorWebAssemblyOptions>(options =>
## Distributed Events ## Distributed Events
This module defines an event for messaging. It is published when a new message is sent from a user to another user, with an Event Transfer Object type of `ChatMessageEto`. See the [standard distributed events](../framework/infrastructure/event-bus/distributed) for more information about distributed events. The module defines the following Event Transfer Object types for real-time operations:
| Event Transfer Object | Operation | SignalR client method |
| --- | --- | --- |
| `ChatMessageEto` | A message is sent. | `ReceiveMessage` |
| `ChatDeletedMessageEto` | A message is deleted. | `DeleteMessage` |
| `ChatDeletedConversationEto` | A conversation is deleted. | `DeleteConversation` |
The default application-layer implementation of `IRealTimeChatMessageSender` publishes these events to the distributed event bus. The `Volo.Chat.SignalR` package replaces that implementation in the SignalR host, handles the distributed events and sends them to the target user through the corresponding SignalR client method. See the [standard distributed events](../framework/infrastructure/event-bus/distributed) for more information about distributed events.

Write Preview
Loading…
Cancel
Save