Chat: support emptyViewTemplate option

Zedwag · web-flow · commit 96894c610641 · 2025-08-21T09:59:23.000+03:00
diff --git a/packages/devextreme-angular/src/ui/chat/index.ts b/packages/devextreme-angular/src/ui/chat/index.ts
@@ -193,6 +193,19 @@ export class DxChatComponent extends DxComponent implements OnDestroy, OnChanges
     }
 
 
+    /**
+     * [descr:dxChatOptions.emptyViewTemplate]
+    
+     */
+    @Input()
+    get emptyViewTemplate(): any {
+        return this._getOption('emptyViewTemplate');
+    }
+    set emptyViewTemplate(value: any) {
+        this._setOption('emptyViewTemplate', value);
+    }
+
+
     /**
      * [descr:dxChatOptions.focusStateEnabled]
     
@@ -565,6 +578,13 @@ export class DxChatComponent extends DxComponent implements OnDestroy, OnChanges
      */
     @Output() elementAttrChange: EventEmitter<Record<string, any>>;
 
+    /**
+    
+     * This member supports the internal infrastructure and is not intended to be used directly from your code.
+    
+     */
+    @Output() emptyViewTemplateChange: EventEmitter<any>;
+
     /**
     
      * This member supports the internal infrastructure and is not intended to be used directly from your code.
@@ -769,6 +789,7 @@ export class DxChatComponent extends DxComponent implements OnDestroy, OnChanges
             { emit: 'disabledChange' },
             { emit: 'editingChange' },
             { emit: 'elementAttrChange' },
+            { emit: 'emptyViewTemplateChange' },
             { emit: 'focusStateEnabledChange' },
             { emit: 'heightChange' },
             { emit: 'hintChange' },
diff --git a/packages/devextreme-react/src/chat.ts b/packages/devextreme-react/src/chat.ts
@@ -31,6 +31,8 @@ type IChatOptionsNarrowedEvents = {
 }
 
 type IChatOptions = React.PropsWithChildren<ReplaceFieldTypes<Properties, IChatOptionsNarrowedEvents> & IHtmlOptions & {
+  emptyViewRender?: (...params: any) => React.ReactNode;
+  emptyViewComponent?: React.ComponentType<any>;
   messageRender?: (...params: any) => React.ReactNode;
   messageComponent?: React.ComponentType<any>;
   defaultItems?: Array<Message>;
@@ -72,6 +74,11 @@ const Chat = memo(
       }), []);
 
       const templateProps = useMemo(() => ([
+        {
+          tmplOption: "emptyViewTemplate",
+          render: "emptyViewRender",
+          component: "emptyViewComponent"
+        },
         {
           tmplOption: "messageTemplate",
           render: "messageRender",
diff --git a/packages/devextreme-vue/src/chat.ts b/packages/devextreme-vue/src/chat.ts
@@ -44,6 +44,7 @@ type AccessibleOptions = Pick<Properties,
   "disabled" |
   "editing" |
   "elementAttr" |
+  "emptyViewTemplate" |
   "focusStateEnabled" |
   "height" |
   "hint" |
@@ -89,6 +90,7 @@ const componentConfig = {
     disabled: Boolean,
     editing: Object as PropType<Record<string, any>>,
     elementAttr: Object as PropType<Record<string, any>>,
+    emptyViewTemplate: {},
     focusStateEnabled: Boolean,
     height: [Number, String],
     hint: String,
@@ -130,6 +132,7 @@ const componentConfig = {
     "update:disabled": null,
     "update:editing": null,
     "update:elementAttr": null,
+    "update:emptyViewTemplate": null,
     "update:focusStateEnabled": null,
     "update:height": null,
     "update:hint": null,
diff --git a/packages/devextreme/js/__internal/ui/chat/chat.ts b/packages/devextreme/js/__internal/ui/chat/chat.ts
@@ -31,6 +31,7 @@ import type {
 } from '@ts/ui/chat/messagebox';
 import MessageBox from '@ts/ui/chat/messagebox';
 import type {
+  EmptyViewTemplate,
   MessageEditingEvent,
   MessageTemplate,
   Properties as MessageListProperties,
@@ -89,6 +90,7 @@ class Chat extends Widget<Properties> {
       dayHeaderFormat: 'shortdate',
       messageTemplate: null,
       messageTimestampFormat: 'shorttime',
+      emptyViewTemplate: null,
       alerts: [],
       showAvatar: true,
       showUserName: true,
@@ -201,6 +203,7 @@ class Chat extends Widget<Properties> {
       allowDeleting: (message: Message): boolean => this._allowDeleteAction(message),
       isEditActionDisabled: (message) => this._messageToEdit === message,
       messageTemplate: this._getMessageTemplate(),
+      emptyViewTemplate: this._getEmptyViewTemplate(),
       showDayHeaders,
       showAvatar,
       showUserName,
@@ -259,17 +262,23 @@ class Chat extends Widget<Properties> {
     return allowDeleting ?? false;
   }
 
-  _getMessageTemplate(): MessageTemplate {
-    const { messageTemplate } = this.option();
-    if (messageTemplate) {
-      return (message, $container): void => {
-        const template = this._getTemplateByOption('messageTemplate');
+  _getRenderTemplateFunction(optionName: 'messageTemplate'): MessageTemplate;
+  _getRenderTemplateFunction(optionName: 'emptyViewTemplate'): EmptyViewTemplate;
+  _getRenderTemplateFunction(
+    optionName: 'messageTemplate' | 'emptyViewTemplate',
+  ): MessageTemplate | EmptyViewTemplate {
+    const { [optionName]: templateOption } = this.option();
+
+    if (templateOption) {
+      return (data, $container): void => {
+        const template = this._getTemplateByOption(optionName);
+        const dataFieldName = optionName === 'messageTemplate' ? 'message' : 'data';
 
         template.render({
           container: $container,
           model: {
             component: this,
-            message,
+            [dataFieldName]: data,
           },
         });
       };
@@ -278,6 +287,14 @@ class Chat extends Widget<Properties> {
     return null;
   }
 
+  _getMessageTemplate(): MessageTemplate {
+    return this._getRenderTemplateFunction('messageTemplate');
+  }
+
+  _getEmptyViewTemplate(): EmptyViewTemplate {
+    return this._getRenderTemplateFunction('emptyViewTemplate');
+  }
+
   _messageEditingStartHandler(e: MessageEditingEvent): void {
     if (this._messageToEdit) {
       this._messageEditCanceledAction?.({ message: this._messageToEdit });
@@ -615,6 +632,9 @@ class Chat extends Widget<Properties> {
       case 'messageTemplate':
         this._messageList.option(name, this._getMessageTemplate());
         break;
+      case 'emptyViewTemplate':
+        this._messageList.option(name, this._getEmptyViewTemplate());
+        break;
       case 'reloadOnChange':
         break;
       default:
diff --git a/packages/devextreme/js/__internal/ui/chat/messagelist.ts b/packages/devextreme/js/__internal/ui/chat/messagelist.ts
@@ -17,6 +17,7 @@ import type { Message, TextMessage, User } from '@js/ui/chat';
 import type { Item as ContextMenuItem } from '@js/ui/context_menu';
 import type dxContextMenu from '@js/ui/context_menu';
 import type { WidgetOptions } from '@js/ui/widget/ui.widget';
+import { getPublicElement } from '@ts/core/m_element';
 import type { OptionChanged } from '@ts/core/widget/types';
 import Widget from '@ts/core/widget/widget';
 import ContextMenu from '@ts/ui/context_menu/context_menu';
@@ -64,6 +65,10 @@ const ESCAPE_KEY = 'escape';
 export const MESSAGEGROUP_TIMEOUT = 5 * 1000 * 60;
 
 export type MessageTemplate = ((data: Message, messageBubbleContainer: Element) => void) | null;
+export type EmptyViewTemplate = ((
+  data: { message: string; prompt: string },
+  emptyViewContainer: Element) => void
+) | null;
 
 export type ItemClick = NativeEventInfo<ContextMenu, KeyboardEvent | MouseEvent | PointerEvent> & {
   readonly itemData?: ContextMenuItem;
@@ -88,6 +93,7 @@ export interface Properties extends WidgetOptions<MessageList> {
   currentUserId: number | string | undefined;
   showDayHeaders: boolean;
   messageTemplate?: MessageTemplate;
+  emptyViewTemplate?: EmptyViewTemplate;
   dayHeaderFormat?: Format;
   messageTimestampFormat?: Format;
   typingUsers: User[];
@@ -131,6 +137,7 @@ class MessageList extends Widget<Properties> {
       showAvatar: true,
       showUserName: true,
       showMessageTimestamp: true,
+      emptyViewTemplate: null,
       messageTemplate: null,
     };
   }
@@ -198,23 +205,34 @@ class MessageList extends Widget<Properties> {
   }
 
   _renderEmptyViewContent(): void {
+    const messageText = messageLocalization.format('dxChat-emptyListMessage');
+    const promptText = messageLocalization.format('dxChat-emptyListPrompt');
+    const { emptyViewTemplate } = this.option();
+
     const $emptyView = $('<div>')
       .addClass(CHAT_MESSAGELIST_EMPTY_VIEW_CLASS)
       .attr('id', `dx-${new Guid()}`);
 
+    if (emptyViewTemplate) {
+      const data = {
+        message: messageText,
+        prompt: promptText,
+      };
+      emptyViewTemplate(data, getPublicElement($emptyView));
+      $emptyView.appendTo(this._$content);
+
+      return;
+    }
+
     $('<div>')
       .appendTo($emptyView)
       .addClass(CHAT_MESSAGELIST_EMPTY_IMAGE_CLASS);
 
-    const messageText = messageLocalization.format('dxChat-emptyListMessage');
-
     $('<div>')
       .appendTo($emptyView)
       .addClass(CHAT_MESSAGELIST_EMPTY_MESSAGE_CLASS)
       .text(messageText);
 
-    const promptText = messageLocalization.format('dxChat-emptyListPrompt');
-
     $('<div>')
       .appendTo($emptyView)
       .addClass(CHAT_MESSAGELIST_EMPTY_PROMPT_CLASS)
@@ -809,6 +827,7 @@ class MessageList extends Widget<Properties> {
       case 'showUserName':
       case 'showMessageTimestamp':
       case 'messageTemplate':
+      case 'emptyViewTemplate':
       case 'dayHeaderFormat':
       case 'messageTimestampFormat':
         this._invalidate();
diff --git a/packages/devextreme/js/ui/chat.d.ts b/packages/devextreme/js/ui/chat.d.ts
@@ -284,6 +284,15 @@ export type MessageTemplateData = {
     readonly message?: Message;
 };
 
+/** @public */
+export type EmptyViewTemplateData = {
+    readonly component: dxChat;
+    readonly data: {
+        readonly message: string;
+        readonly prompt: string;
+    };
+};
+
 /**
  * @deprecated use Properties instead
  * @namespace DevExpress.ui
@@ -339,6 +348,13 @@ export interface dxChatOptions extends WidgetOptions<dxChat> {
        */
       allowDeleting?: boolean | ((options: { component?: dxChat; message?: Message }) => boolean);
     };
+    /**
+     * @docid
+     * @default null
+     * @type_function_return string|Element|jQuery
+     * @public
+     */
+    emptyViewTemplate?: template | null | ((data: EmptyViewTemplateData, itemElement: DxElement) => string | UserDefinedElement);
     /**
      * @docid
      * @type string | Array<Message> | Store | DataSource | DataSourceOptions | null
diff --git a/packages/devextreme/js/ui/chat_types.d.ts b/packages/devextreme/js/ui/chat_types.d.ts
@@ -17,6 +17,7 @@ export {
   ImageMessage,
   Message,
   MessageTemplateData,
+  EmptyViewTemplateData,
   dxChatOptions,
   Properties,
 } from './chat';
diff --git a/packages/devextreme/testing/tests/DevExpress.ui.widgets/chatParts/chat.tests.js b/packages/devextreme/testing/tests/DevExpress.ui.widgets/chatParts/chat.tests.js
@@ -28,6 +28,7 @@ import fx from 'common/core/animation/fx';
 import { isRenderer } from 'core/utils/type';
 
 import config from 'core/config';
+import localization from 'localization';
 import ArrayStore from 'common/data/array_store';
 import {
     CHAT_EDITING_PREVIEW_CLASS,
@@ -122,6 +123,7 @@ const moduleConfig = {
         this.getContextMenuItems = () => $(this.getContextMenu().itemsContainer()).find(`.${DX_MENU_ITEM_CLASS}`);
         this.getEditingPreview = () => this.$element.find(`.${CHAT_EDITING_PREVIEW_CLASS}`);
         this.getCancelEditingButton = () => this.$element.find(`.${CHAT_EDITING_PREVIEW_CANCEL_BUTTON_CLASS}`);
+        this.getMessageListEmptyView = () => this.$element.find(`.${CHAT_MESSAGELIST_EMPTY_VIEW_CLASS}`);
 
         init();
     },
@@ -758,6 +760,81 @@ QUnit.module('Chat', () => {
             });
         });
 
+        QUnit.module('emptyViewTemplate', () => {
+            QUnit.test('emptyViewTemplate should set empty view content on init', function(assert) {
+                this.reinit({
+                    emptyViewTemplate: () => $('<h1>').text('This is empty'),
+                });
+
+                const $emptyView = this.getMessageListEmptyView();
+
+                assert.strictEqual($emptyView.text(), 'This is empty');
+            });
+
+            QUnit.test('emptyViewTemplate should set empty view content at runtime', function(assert) {
+                this.reinit({ });
+                this.instance.option('emptyViewTemplate', () => $('<h1>').text('This is empty'));
+
+                const $emptyView = this.getMessageListEmptyView();
+
+                assert.strictEqual($emptyView.text(), 'This is empty');
+            });
+
+            QUnit.test('emptyViewTemplate specified as a string text should set empty view content', function(assert) {
+                this.reinit({ emptyViewTemplate: 'empty' });
+
+                const $emptyView = this.getMessageListEmptyView();
+
+                assert.strictEqual($emptyView.text(), 'empty');
+            });
+
+            QUnit.test('emptyViewTemplate specified as a string with a html element should set empty view content', function(assert) {
+                this.reinit({ emptyViewTemplate: '<p>p text</p>' });
+
+                const $emptyViewChild = this.getMessageListEmptyView().children();
+
+                assert.strictEqual($emptyViewChild.text(), 'p text', 'template text is correct');
+                assert.strictEqual($emptyViewChild.prop('tagName'), 'P', 'templte tag element is correct');
+            });
+
+            QUnit.test('emptyViewTemplate function argument should include Chat instance', function(assert) {
+                assert.expect(1);
+
+                const emptyViewTemplate = (data) => {
+                    assert.strictEqual(data.component instanceof Chat, true, 'chat instance is passed');
+                };
+
+                this.reinit({ emptyViewTemplate });
+            });
+
+            QUnit.test('emptyViewTemplate function argument should include data with localized message and prompt', function(assert) {
+                assert.expect(2);
+
+                const defaultLocale = localization.locale();
+                const localizedEmptyListMessage = 'Lista wiadomości jest pusta';
+                const localizedEmptyListPrompt = 'Napisz swoją pierwszą wiadomość';
+
+                const emptyViewTemplate = ({ data }) => {
+                    assert.strictEqual(data.message, localizedEmptyListMessage, 'localized message is passed');
+                    assert.strictEqual(data.prompt, localizedEmptyListPrompt, 'localized prompt is passed');
+                };
+
+                try {
+                    localization.loadMessages({
+                        'pl': {
+                            'dxChat-emptyListMessage': localizedEmptyListMessage,
+                            'dxChat-emptyListPrompt': localizedEmptyListPrompt,
+                        }
+                    });
+                    localization.locale('pl');
+
+                    this.reinit({ emptyViewTemplate });
+                } finally {
+                    localization.locale(defaultLocale);
+                }
+            });
+        });
+
         QUnit.test('dayHeaderFormat option value should be passed to messageList on init', function(assert) {
             const dayHeaderFormat = 'dd of MMMM, yyyy';
 
diff --git a/packages/devextreme/ts/dx.all.d.ts b/packages/devextreme/ts/dx.all.d.ts
