diff --git a/components/chat/file-uploads-and-media.md b/components/chat/file-uploads-and-media.md index a22b98292..28a3ad091 100644 --- a/components/chat/file-uploads-and-media.md +++ b/components/chat/file-uploads-and-media.md @@ -21,6 +21,21 @@ Enable file uploads by setting the `EnableFileUpload` parameter to `true`: ```` +## Message Files Layout + +The `MessageFilesLayoutMode` parameter controls how file attachments are displayed within chat messages. Choose from three layout options to best fit your application's design: + +* `ChatMessageFilesLayoutMode.Vertical`—Files are displayed in a vertical stack (default) +* `ChatMessageFilesLayoutMode.Horizontal`—Files are displayed in a horizontal row +* `ChatMessageFilesLayoutMode.Wrap`—Files wrap to the next line when they exceed the message width + +````RAZOR.skip-repl + + +```` + ## File Upload Settings Configure file upload behavior using the `ChatFileSelectSettings` component: diff --git a/components/chat/messages.md b/components/chat/messages.md index 799715e7d..b2fa9cca2 100644 --- a/components/chat/messages.md +++ b/components/chat/messages.md @@ -12,6 +12,71 @@ position: 5 The Telerik UI for Blazor Chat component provides comprehensive control over message display, interactions, and styling to create rich conversational experiences. +## Typing Indicator + +The Chat supports displaying a typing indicator to show when another user is composing a message. When a message has `IsTyping` set to `true`, the component will display an animated typing indicator (typically three dots) instead of the message content. This provides visual feedback that enhances the conversational experience, especially in real-time chat scenarios. + +First, set the `IsTypingField` parameter to specify which field in your data model indicates typing status. Next, set that field to `true` on a message to display the typing indicator. + +````Razor +Show Typing Indicator + + + + +@code { + private TelerikChat ChatRef { get; set; } + private List ChatData { get; set; } = new(); + private string CurrentUserId { get; set; } = "user1"; + + private void AddTypingMessage() + { + var typingMessage = new ChatMessage + { + Id = Guid.NewGuid().ToString(), + Content = null, + AuthorId = "support", + AuthorName = "Support Agent", + Timestamp = DateTime.Now, + IsTyping = true + }; + + ChatData.Add(typingMessage); + } + + private void OnChatSendMessage(ChatSendMessageEventArgs args) + { + ChatData.RemoveAll(m => m.IsTyping); + + var newMessage = new ChatMessage + { + Id = Guid.NewGuid().ToString(), + Content = args.Message, + AuthorId = CurrentUserId, + Timestamp = DateTime.Now + }; + + ChatData.Add(newMessage); + ChatRef?.Refresh(); + } + + public class ChatMessage + { + public string Id { get; set; } + public string AuthorId { get; set; } + public string AuthorName { get; set; } + public string Content { get; set; } + public bool IsTyping { get; set; } + public DateTime Timestamp { get; set; } + } +} +```` + ## Context Menu Message Actions Configure context menu actions that appear when users right-click on messages. These actions provide quick access to common message operations. @@ -179,6 +244,145 @@ Control the width behavior of chat messages using the `MessageWidthMode` paramet * `MessageWidthMode.Standard` - Messages take up a portion of the available space for better readability (default behavior) * `MessageWidthMode.Full` - Messages span the full width of the chat container +## Author and Receiver Message Settings + +The Chat component lets you configure settings specifically for author messages (sent by the current user) and receiver messages (received from other users) using `ChatAuthorMessageSettings` and `ChatReceiverMessageSettings` components. These settings take precedence over global Chat settings, enabling different configurations for sent and received messages. + +Use these settings to customize message behavior, appearance, and available actions based on whether the message was sent or received. For example, you might want different context menu actions, toolbar actions, or file actions for your own messages versus messages from others. + +````Razor + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +@code { + private TelerikChat ChatRef { get; set; } + private List ChatData { get; set; } = new() + { + new ChatMessage() + { + Id = "1", + AuthorId = "support", + Content = "Hello! How can I assist you today?", + Timestamp = DateTime.Now.AddMinutes(-10) + }, + new ChatMessage() + { + Id = "2", + AuthorId = "user1", + Content = "Hi, I have a question about the new features.", + Timestamp = DateTime.Now.AddMinutes(-5) + } + }; + private string CurrentUserId { get; set; } = "user1"; + + private void OnChatSendMessage(ChatSendMessageEventArgs args) + { + var newMessage = new ChatMessage + { + Id = Guid.NewGuid().ToString(), + Content = args.Message, + AuthorId = CurrentUserId, + Timestamp = DateTime.Now + }; + + ChatData.Add(newMessage); + } + + private void PinMessage(ChatMessageActionClickEventArgs args) + { + var message = ChatData.FirstOrDefault(m => m.Id == args.MessageId); + if (message != null) + { + message.IsPinned = true; + ChatRef?.Refresh(); + } + } + + private void ReactToMessage(ChatMessageActionClickEventArgs args) + { + Console.WriteLine($"Liked message: {args.MessageId}"); + } + + public class ChatMessage + { + public string Id { get; set; } + public string AuthorId { get; set; } + public string Content { get; set; } + public bool IsPinned { get; set; } + public DateTime Timestamp { get; set; } + } +} +```` + +`ChatAuthorMessageSettings` and `ChatReceiverMessageSettings` provide the following settings: + +* `EnableMessageCollapse`—Enables the collapse functionality for long messages +* `MessageWidthMode`—Controls message width (`Standard` or `Full`) +* `ChatMessageContextMenuActions`—Defines context menu actions for right-click interactions +* `ChatMessageToolbarActions`—Defines toolbar actions that appear on hover or selection +* `ChatFileActions`—Defines actions available for file attachments + +If no author or receiver-specific setting is provided, the component falls back to the global Chat settings. + +## Send Message Button Customization + +Customize the appearance of the send message button using the `ChatSendMessageButtonSettings` component. The `Class` parameter allows you to apply custom CSS classes for styling. + +````Razor + + + + + + + +```` + ## Message Box Value Persistence The message box value represents the text that users have typed but haven't sent yet. diff --git a/components/chat/overview.md b/components/chat/overview.md index c3501d362..964667686 100644 --- a/components/chat/overview.md +++ b/components/chat/overview.md @@ -130,20 +130,24 @@ The Chat component provides a variety of parameters: | Parameter | Type and Default Value | Description | | --- | --- | --- | -| `Data` | `IEnumerable` | The data source for chat messages. | +| `AttachmentsField` | `string`
(`"Attachments"`) | The name of the field containing message file attachments. | | `AuthorId` | `string` | The ID of the current user sending messages. | -| `TextField` | `string`
(`"Text"`) | The name of the field containing the message content. | | `AuthorIdField` | `string`
(`"AuthorId"`) | The name of the field containing the author identifier. | -| `TimestampField` | `string`
(`"Timestamp"`) | The name of the field containing the message timestamp. | -| `AuthorNameField` | `string`
(`"AuthorName"`) | The name of the field containing the author display name. | | `AuthorImageUrlField` | `string`
(`"AuthorImageUrl"`) | The name of the field containing the author's avatar image URL. | -| `AttachmentsField` | `string`
(`"Attachments"`) | The name of the field containing message file attachments. | -| `Height` | `string` | The height of the chat component in CSS units. | -| `Width` | `string` | The width of the chat component in CSS units. | +| `AuthorNameField` | `string`
(`"AuthorName"`) | The name of the field containing the author display name. | +| `Data` | `IEnumerable` | The data source for chat messages. | | `EnableFileUpload` | `bool`
(`false`) | Enables file upload functionality in the chat input. | | `EnableSpeechToText` | `bool`
(`true`) | Enables speech-to-text functionality with microphone input. | +| `Height` | `string` | The height of the chat component in CSS units. | +| `IsTypingField` | `string` | The name of the field that indicates whether a message represents a typing indicator. | +| `MessageFilesLayoutMode` | `ChatMessageFilesLayoutMode` enum
(`Vertical`) | Controls how file attachments are displayed (Vertical, Horizontal, or Wrap). | | `MessageWidthMode` | `MessageWidthMode` enum
(`Standard`) | Controls the width behavior of messages (Standard or Full). | +| `SuggestedActionsLayoutMode` | `ChatSuggestedActionsLayoutMode` enum
(`Wrap`) | Controls how suggested actions are displayed (Wrap, Scroll, or ScrollButtons). | | `Suggestions` | `IEnumerable` | Collection of quick reply suggestions. | +| `SuggestionsLayoutMode` | `ChatSuggestionsLayoutMode` enum
(`Wrap`) | Controls how message suggestions are displayed (Wrap, Scroll, or ScrollButtons). | +| `TextField` | `string`
(`"Text"`) | The name of the field containing the message content. | +| `TimestampField` | `string`
(`"Timestamp"`) | The name of the field containing the message timestamp. | +| `Width` | `string` | The width of the chat component in CSS units. | ## Chat Reference and Methods diff --git a/components/chat/quick-actions.md b/components/chat/quick-actions.md index a7a275a86..13aee4bae 100644 --- a/components/chat/quick-actions.md +++ b/components/chat/quick-actions.md @@ -16,6 +16,103 @@ The Telerik UI for Blazor Chat component supports quick actions and message sugg Message suggestions provide users with quick reply options that appear below the message input area. +## Suggestions Layout Mode + +The `SuggestionsLayoutMode` parameter controls how suggestions are displayed in the chat interface. Choose from three layout options to optimize the presentation based on the number and length of your suggestions: + +* `ChatSuggestionsLayoutMode.Wrap`—Suggestions wrap to the next line if they exceed the container width (default) +* `ChatSuggestionsLayoutMode.Scroll`—Suggestions are displayed in a single line with horizontal scrolling +* `ChatSuggestionsLayoutMode.ScrollButtons`—Suggestions are displayed in a single line with horizontal scrolling and navigation + +Use `Scroll` or `ScrollButtons` mode when you have many suggestions or longer text that won't fit comfortably in the available width. The `ScrollButtons` mode is particularly helpful for users who prefer button navigation over scrolling gestures. + +````Razor + + + +@code { + private List ChatData { get; set; } = new(); + + private List QuickReplies = new List + { + "Request project status update", + "Schedule a follow-up meeting", + "Review document", + "Send report", + "Approve changes" + }; + + private void HandleSuggestionClick(ChatSuggestionClickEventArgs args) + { + // Handle suggestion click + } + + public class ChatMessage + { + public string Id { get; set; } + public string AuthorId { get; set; } + public string Content { get; set; } + public DateTime Timestamp { get; set; } + } +} +```` + +## Suggested Actions Layout Mode + +The `SuggestedActionsLayoutMode` parameter controls how suggested actions (quick actions attached to specific messages) are displayed. Similar to `SuggestionsLayoutMode`, it offers three layout options: + +* `ChatSuggestedActionsLayoutMode.Wrap`—Suggested actions wrap to the next line (default) +* `ChatSuggestedActionsLayoutMode.Scroll`—Suggested actions are displayed in a single line with horizontal scrolling +* `ChatSuggestedActionsLayoutMode.ScrollButtons`—Suggested actions are displayed in a single line with horizontal scrolling and navigation buttons + +````Razor + + + +@code { + private List ChatData { get; set; } = new() + { + new ChatMessage + { + Id = "1", + AuthorId = "bot", + Content = "How would you like to proceed?", + Timestamp = DateTime.Now, + SuggestedActions = new List + { + "Option 1: Quick action", + "Option 2: Detailed review", + "Option 3: Schedule later", + "Option 4: Request more info" + } + } + }; + + private void HandleSendMessage(ChatSendMessageEventArgs args) + { + // Handle send message + } + + public class ChatMessage + { + public string Id { get; set; } + public string AuthorId { get; set; } + public string Content { get; set; } + public DateTime Timestamp { get; set; } + public List SuggestedActions { get; set; } + } +} +```` + +Suggested actions are contextual quick replies that appear below specific messages, helping guide users through conversations or workflows. The layout mode ensures they are displayed effectively regardless of their number or length. + >caption Basic message suggestions ````razor diff --git a/components/chat/templates.md b/components/chat/templates.md index d5fb697e6..ee2d3df42 100644 --- a/components/chat/templates.md +++ b/components/chat/templates.md @@ -27,18 +27,110 @@ This template allows you to customize the Chat header, where you can display tit ```` -## MessageTemplate +## NoDataTemplate -Customize how individual messages are rendered within the Chat. +The `NoDataTemplate` lets you to define custom content displayed when the Chat has no messages. This is useful for showing welcome messages, instructions, or branding when the conversation is empty. ````RAZOR.skip-repl - + +

No Messages Available.

+

Start a conversation by typing a message below!

+ +```` + +## MessageContentTemplate + +The `MessageContentTemplate` provides the option to customize how individual message content is rendered within the Chat. + +````RAZOR.skip-repl +
@context.Message.Content
+ +```` + +## AuthorMessageContentTemplate + +The `AuthorMessageContentTemplate` allows you to customize the appearance of message content for messages sent by the current user (author). This template takes precedence over `MessageContentTemplate` when defined, enabling different styling for sent versus received messages. + +````RAZOR.skip-repl + +
+ @context.Message.Content +
+ +```` + +## ReceiverMessageContentTemplate + +The `ReceiverMessageContentTemplate` allows you to customize the appearance of message content for messages received from other users. This template takes precedence over `MessageContentTemplate` when defined, providing flexibility to style incoming messages differently. + +````RAZOR.skip-repl + +
+ @context.Message.Content +
+ +```` + +## MessageTemplate + +The `MessageTemplate` allows you to customize the entire message bubble rendering, including the wrapper and structure around the message content. This provides complete control over the message appearance. + +````RAZOR.skip-repl + +
+
@context.Message.AuthorName
+
@context.Message.Content
+
```` +## AuthorMessageTemplate + +The `AuthorMessageTemplate` allows you to customize the entire message bubble for messages sent by the current user (author). This template takes precedence over `MessageTemplate` when defined, enabling control over the author's message structure and appearance. + +````RAZOR.skip-repl + +
+
@context.Message.Content
+
@context.Message.Timestamp.ToString("hh:mm tt")
+
+ +```` + +## ReceiverMessageTemplate + +The `ReceiverMessageTemplate` allows you to customize the entire message bubble for messages received from other users. This template takes precedence over `MessageTemplate` when defined, providing the option to specify how incoming messages are structured and displayed. + +````RAZOR.skip-repl + +
+
@context.Message.AuthorName
+
@context.Message.Content
+
@context.Message.Timestamp.ToString("hh:mm tt")
+
+ +```` + +## UserStatusTemplate + +The `UserStatusTemplate` allows you to render custom content next to the user avatar, such as status badges, indicators, or icons. This is useful for showing user availability (online, away, busy) or other contextual information. + +````RAZOR.skip-repl + + @if (context.Message.AuthorStatus == "online") + { + + } + else if (context.Message.AuthorStatus == "away") + { + + } + +```` + ## MessageStatusTemplate You can use this template to display the status of a message (e.g., Sent, Seen). @@ -102,7 +194,7 @@ This allows you to define context menu actions that can be performed on Chat mes >caption A complete example that integrates all templates into a Chat component -````RAZOR.skip-repl +````RAZOR + +

No Messages Available.

+
@context.Message.Status
- -
+ +
@context.Message.Content
- + + +
+ @context.Message.Content +
+ + + @if (context.Message.AuthorStatus == "online") + { + + } +
@context.Suggestion @@ -152,7 +258,7 @@ This allows you to define context menu actions that can be performed on Chat mes @code { #region Component References - private TelerikChat? ChatRef { get; set; } + private TelerikChat ChatRef { get; set; } #endregion @@ -216,7 +322,6 @@ This allows you to define context menu actions that can be performed on Chat mes Id = Guid.NewGuid().ToString(), AuthorName = authorId == "1" ? "John Smith" : "Jane Doe", AuthorId = authorId, - AuthorImageUrl = authorId == "1" ? FirstUserImage : SecondUserImage, Content = args.Message, MessageToReplyId = args.ReplyMessageId, Status = "Sent", @@ -255,7 +360,6 @@ This allows you to define context menu actions that can be performed on Chat mes Id = $"message{i}", AuthorId = (i % 2 == 1) ? "1" : "2", AuthorName = (i % 2 == 1) ? "John Smith" : "Jane Doe", - AuthorImageUrl = (i % 2 == 1) ? FirstUserImage : SecondUserImage, Content = messageTexts[i - 1], Status = "Seen", Timestamp = new DateTime(2023, 10, 1, 12, 0, 0).AddMinutes(i * 5) @@ -273,11 +377,13 @@ This allows you to define context menu actions that can be performed on Chat mes public string AuthorId { get; set; } public string AuthorName { get; set; } public string AuthorImageUrl { get; set; } + public string AuthorStatus { get; set; } public string Content { get; set; } public string MessageToReplyId { get; set; } public string Status { get; set; } public bool IsDeleted { get; set; } public bool IsPinned { get; set; } + public bool IsTyping { get; set; } public DateTime Timestamp { get; set; } public List SuggestedActions { get; set; } public IEnumerable Attachments { get; set; } = new List();