Chat: Add suggestions API Description#8674
Chat: Add suggestions API Description#8674arman-boyakhchyan wants to merge 7 commits intoDevExpress:26_1from
Conversation
There was a problem hiding this comment.
Pull request overview
Adds API reference content for dxChat.Options.suggestions to describe how to configure suggestion buttons above the Chat input field.
Changes:
- Documented how
suggestionsmaps to a DevExtreme ButtonGroup configuration (including ignored/overridden options). - Added multi-framework code snippets (jQuery/Angular/Vue/React) demonstrating suggestion buttons that populate
inputFieldText.
| return ( | ||
| <Chat | ||
| inputFieldText={inputFieldText} | ||
| suggestions={chatSuggestions} | ||
| /> |
There was a problem hiding this comment.
In the React sample, inputFieldText is supplied from React state, but there is no onInputFieldTextChange handler to keep that state updated when the user types. This can lead to state/UI divergence (and the value being reset on re-render). Add the change handler (see the existing inputFieldText option example for the pattern).
| { text: 'Fix my writing' }, | ||
| ], | ||
| onItemClick: handleSuggestionClick, | ||
| } |
There was a problem hiding this comment.
Missing semicolon after the chatSuggestions object literal; most TypeScript/React samples in this section terminate statements with semicolons. Add the semicolon to avoid lint/style inconsistencies in the snippet.
| } | |
| }; |
| $('#chat').dxChat({ | ||
| suggestions: { | ||
| items: [ | ||
| { text: 'Summarize text' }, | ||
| { text: 'Write an email' }, | ||
| { text: 'Fix my writing' }, | ||
| ], | ||
| onItemClick(e) { | ||
| $('#chat').dxChat('instance').option('inputFieldText', e.itemData.text); | ||
| }, |
There was a problem hiding this comment.
In the jQuery snippet, the handler calls $('#chat').dxChat('instance') on every click, which repeats DOM lookup and instance retrieval. Store the Chat instance once during initialization (or keep it in a variable/closure) and reuse it inside onItemClick.
| </dx-chat> | ||
|
|
||
| <!-- tab: app.component.ts --> | ||
| import { DxChatModule, type DxChatTypes } from "devextreme-angular/ui/chat"; |
There was a problem hiding this comment.
The Angular example imports DxChatModule, but the snippet does not use it anywhere (and it is not paired with an app.module.ts tab). Consider removing this import or adding the module-setup snippet where DxChatModule is actually used to avoid confusion and unused-import warnings.
| import { DxChatModule, type DxChatTypes } from "devextreme-angular/ui/chat"; | |
| import { type DxChatTypes } from "devextreme-angular/ui/chat"; |
|
|
||
| <!-- tab: app.component.html --> | ||
| <dx-chat ... | ||
| [inputFieldText]="inputFieldText" |
There was a problem hiding this comment.
The Angular template binds [inputFieldText] one-way, so the component field will not reflect user edits in the input. If the intent is to keep inputFieldText in sync with the UI (as in the existing inputFieldText option docs), use two-way binding ([(inputFieldText)]) or handle the corresponding change event.
| [inputFieldText]="inputFieldText" | |
| [(inputFieldText)]="inputFieldText" |
| --- | ||
| Use this object to specify predefined messages or execute actions outside of the Chat. To implement suggestions, configure the following [ButtonGroup properties](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/): | ||
|
|
||
| - The [items[]](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/items/) array |
There was a problem hiding this comment.
Do I understand it correctly that button captions and text pasted into the message input are always the same? Can I have a shorter button caption ("Weather") and a longer prompt pasted into the input ("Give me a weather report for the following week and specifically focus on changes of precipitation.") ?
That seems like it should be a common task, but I don't see if that's possible.
There was a problem hiding this comment.
Yes, that is possible. To achieve this, customers need to specify a separate custom field for the message in the items[] array (in addition to text). Then, in the onItemClick handler, this custom message field would need to be used instead of text. We have even implemented this approach in an upcoming DevExtreme Chat demo.
Co-authored-by: Vladimir Abadzhev <vladimira@devexpress.com>
| Use this object to specify predefined messages or execute actions outside of the Chat. To implement suggestions, configure the following [ButtonGroup properties](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/): | ||
|
|
||
| - The [items[]](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/items/) array | ||
| - An [onItemClick](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/#onItemClick) handler | ||
|
|
||
| The Chat component ignores the following ButtonGroup options in the **suggestions** object: | ||
|
|
||
| - [selectionMode](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/#selectionMode) | ||
| - [selectedItemKeys](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/#selectedItemKeys) | ||
| - [selectedItems](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/#selectedItems) | ||
| - [onSelectionChanged](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/#onSelectionChanged) | ||
|
|
||
| The Chat component overrides the default values of the following ButtonGroup properties: | ||
|
|
||
| - **items[]**.[type](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/items/#type): *"default"* | ||
| - [stylingMode](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/#stylingMode): *"outlined"* |
There was a problem hiding this comment.
The new ButtonGroup API links in this section use the /Documentation/ApiReference/... URL format. In the dxChat API reference, links typically use the /api-reference/... path with an optional '/Documentation/...' title (for example, dxChat/1 Configuration/sendButtonOptions.md:12). Please update these ButtonGroup links (items, onItemClick, selectionMode, selectedItemKeys, selectedItems, onSelectionChanged, stylingMode, items[].type) to match the established /api-reference/... format used elsewhere in this folder.
| Use this object to specify predefined messages or execute actions outside of the Chat. To implement suggestions, configure the following [ButtonGroup properties](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/): | |
| - The [items[]](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/items/) array | |
| - An [onItemClick](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/#onItemClick) handler | |
| The Chat component ignores the following ButtonGroup options in the **suggestions** object: | |
| - [selectionMode](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/#selectionMode) | |
| - [selectedItemKeys](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/#selectedItemKeys) | |
| - [selectedItems](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/#selectedItems) | |
| - [onSelectionChanged](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/#onSelectionChanged) | |
| The Chat component overrides the default values of the following ButtonGroup properties: | |
| - **items[]**.[type](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/items/#type): *"default"* | |
| - [stylingMode](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/#stylingMode): *"outlined"* | |
| Use this object to specify predefined messages or execute actions outside of the Chat. To implement suggestions, configure the following [ButtonGroup properties](/api-reference/ui-components/dxbuttongroup/Configuration/): | |
| - The [items[]](/api-reference/ui-components/dxbuttongroup/Configuration/items/) array | |
| - An [onItemClick](/api-reference/ui-components/dxbuttongroup/Configuration/#onItemClick) handler | |
| The Chat component ignores the following ButtonGroup options in the **suggestions** object: | |
| - [selectionMode](/api-reference/ui-components/dxbuttongroup/Configuration/#selectionMode) | |
| - [selectedItemKeys](/api-reference/ui-components/dxbuttongroup/Configuration/#selectedItemKeys) | |
| - [selectedItems](/api-reference/ui-components/dxbuttongroup/Configuration/#selectedItems) | |
| - [onSelectionChanged](/api-reference/ui-components/dxbuttongroup/Configuration/#onSelectionChanged) | |
| The Chat component overrides the default values of the following ButtonGroup properties: | |
| - **items[]**.[type](/api-reference/ui-components/dxbuttongroup/Configuration/items/#type): *"default"* | |
| - [stylingMode](/api-reference/ui-components/dxbuttongroup/Configuration/#stylingMode): *"outlined"* |
| - **items[]**.[type](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/items/#type): *"default"* | ||
| - [stylingMode](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/#stylingMode): *"outlined"* | ||
|
|
||
| The following code snippet configures **suggestions** that fill the Chat input field ([inputFieldText](/Documentation/ApiReference/UI_Components/dxChat/Configuration/#inputFieldText)) with predefined messages: |
There was a problem hiding this comment.
The link to inputFieldText uses a /Documentation/ApiReference/... URL. For consistency with other dxChat option docs in this folder (for example, dataSource.md:11-16), consider linking via the /api-reference/10%20UI%20Components/dxChat/1%20Configuration/inputFieldText.md path (with the usual '/Documentation/...' title) instead.
| The following code snippet configures **suggestions** that fill the Chat input field ([inputFieldText](/Documentation/ApiReference/UI_Components/dxChat/Configuration/#inputFieldText)) with predefined messages: | |
| The following code snippet configures **suggestions** that fill the Chat input field ([inputFieldText](/api-reference/10%20UI%20Components/dxChat/1%20Configuration/inputFieldText.md)) with predefined messages: |
…entation into chat-suggestions-api-26-1
| Configures suggestion buttons (DevExtreme [ButtonGroup](/Documentation/Guide/UI_Components/ButtonGroup/Getting_Started_with_ButtonGroup/)) displayed above the Chat input field. | ||
|
|
||
| --- | ||
| Use this object to specify predefined messages or execute actions outside of the Chat. To implement suggestions, configure the following [ButtonGroup properties](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/): |
There was a problem hiding this comment.
The sentence "To implement suggestions, configure ..." starts with an introductory dependent clause followed by a comma. Consider rewriting to avoid this structure (for example, "Configure the following ButtonGroup properties to implement suggestions:") to match the documentation style guidelines used in this repo.
| Use this object to specify predefined messages or execute actions outside of the Chat. To implement suggestions, configure the following [ButtonGroup properties](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/): | |
| Use this object to specify predefined messages or execute actions outside of the Chat. Configure the following [ButtonGroup properties](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/) to implement suggestions: |
| const suggestions = { | ||
| items: [{ | ||
| text: 'Weather Report', | ||
| message: 'Give me a weather report for the upcoming week, focus on changes in precipitation', |
There was a problem hiding this comment.
The example message text contains a comma splice ("...week, focus...") which reads like two sentences. Consider updating the sample text to use a period or conjunction for correct grammar (this text is user-facing in the snippet).
| message: 'Give me a weather report for the upcoming week, focus on changes in precipitation', | |
| message: 'Give me a weather report for the upcoming week. Focus on changes in precipitation', |
| - The [items[]](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/items/) array | ||
| - An [onItemClick](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/#onItemClick) handler | ||
|
|
||
| You can store message texts in the **items[]**.[text](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/items/#text) field. This approach specifies identical values for message texts and suggestion button captions. To use different texts, specify message texts in a custom field: |
There was a problem hiding this comment.
I'm not sure why you say "a custom field" (instead of "the message field"). Do you mean that this value will not be automatically used as message text? I'm guessing I should write code that obtains that message and pastes it to the message box?
Does the following change sound right?
| You can store message texts in the **items[]**.[text](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/items/#text) field. This approach specifies identical values for message texts and suggestion button captions. To use different texts, specify message texts in a custom field: | |
| If you only specify the [text](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/items/#text) field for array items, the same text is used as the button caption and the corresponding chat message. In many cases you would prefer to use two strings: a shorter button caption and an expanded message. To specify a separate message text, assign it to a custom field and then obtain that message in the `onItemClick` handler: |
There was a problem hiding this comment.
As part of our suggestions feature, no specific field is automatically used within actions (onItemClick handlers). Customers must manually configure which item field is used when a suggestion is clicked, whether they choose to use text or something else. As for message, this is a custom field because dxButtonGroup.items[] does not contain such a field.
To add clarity to this paragraph, it is more accurate to say that specifying message texts in text makes message texts and suggestion captions identical. Furthermore, rather than instructing customers to specify message texts in a custom field, we can emphasize the creation of a custom field itself. What do you think?
| You can store message texts in the **items[]**.[text](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/items/#text) field. This approach specifies identical values for message texts and suggestion button captions. To use different texts, specify message texts in a custom field: | |
| You can store message texts in the **items[]**.[text](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/items/#text) field. If you use this approach, message texts and suggestion captions are identical. To specify different texts, define a custom field for message texts: |
There was a problem hiding this comment.
We are kind of returning back to a previous version. You just said that regardless of options, the message text must be specified manually in the handler. So now the second sentence seems misleading ("if you use this approach, message and caption are identical"). They are only identical, provided I write certain code in the handler. So how about this version that - that should consolidate all those details:
| You can store message texts in the **items[]**.[text](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/items/#text) field. This approach specifies identical values for message texts and suggestion button captions. To use different texts, specify message texts in a custom field: | |
| The [text](/Documentation/ApiReference/UI_Components/dxButtonGroup/Configuration/items/#text) field in an array item specifies the corresponding button caption. When handling the `onItemClick` event, you can choose to use the same text as a chat message. But in many cases you would prefer to use two strings: a shorter button caption and an extended message. To specify a separate message text, assign it to a custom field: |
No description provided.