Skip to content

Commit cbaa143

Browse files
Tsvetomir-HrTsvetomir-Hr
authored
Aiprompt docs update (#3163)
* docs(AIPrompt): update docs * chore: add rendering and breaking changes articles for version 10.0.0 * chore: polish aiprompt docs * chore: apply review changes and add omitted event
1 parent fcf99af commit cbaa143

File tree

6 files changed

+117
-49
lines changed

6 files changed

+117
-49
lines changed

‎components/aiprompt/events.md

Lines changed: 49 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,51 @@ position: 40
1212

1313
This article explains the events available in the Telerik AIPrompt for Blazor:
1414

15+
* [`OnOutputActionClick`](#onoutputactionclick)
1516
* [`OnPromptRequest`](#onpromptrequest)
17+
* [`OnPromptRequestStop`](#onpromptrequeststo)
1618
* [`OnCommandExecute`](#oncommandexecute)
17-
* [`OnOutputRate`](#onoutputrate)
1819
* [`PromptTextChanged`](#prompttextchanged)
1920

21+
## OnOutputActionClick
22+
23+
The `OnOutputActionClick` event fires when the user clicks an output action button in the output view of the AIPrompt component. Use this event to handle custom actions such as copying, retrying, or providing feedback on the generated output.
24+
25+
To define the available output actions, set the `OutputActions` parameter to a list of [`AIPromptOutputActionDescriptor`](slug:Telerik.Blazor.Components.AIPromptOutputActionDescriptor) objects. Each action descriptor configures the appearance and behavior of an action button.
26+
27+
The event handler receives an argument of type `AIPromptOutputActionClickEventArgs`, which provides details about the clicked action, the prompt, the output, and the related command (if any). For a full list of available properties, refer to the [`AIPromptOutputActionClickEventArgs` API reference](slug:Telerik.Blazor.Components.AIPromptOutputActionClickEventArgs).
28+
29+
>caption Handle output action clicks in the AIPrompt
30+
31+
````RAZOR
32+
<TelerikAIPrompt OutputActions="@OutputActions"
33+
OnOutputActionClick="@OnOutputActionClick"
34+
OnPromptRequest="@HandlePromptRequest">
35+
</TelerikAIPrompt>
36+
37+
@code {
38+
private void OnOutputActionClick(AIPromptOutputActionClickEventArgs args)
39+
{
40+
// Handle the output action click event
41+
Console.WriteLine($"Action clicked: {args.Action.Name}");
42+
}
43+
44+
private List<AIPromptOutputActionDescriptor> OutputActions { get; set; } = new List<AIPromptOutputActionDescriptor>()
45+
{
46+
new AIPromptOutputActionDescriptor() { Name = "Copy", Icon = nameof(SvgIcon.Copy) },
47+
new AIPromptOutputActionDescriptor() { Name = "Retry", Icon = nameof(SvgIcon.Share) },
48+
new AIPromptOutputActionDescriptor() { Icon = SvgIcon.ThumbUp, Name = "Thumbs Up" },
49+
new AIPromptOutputActionDescriptor() { Icon = SvgIcon.ThumbDown, Name = "Thumbs Down" }
50+
};
51+
52+
private void HandlePromptRequest(AIPromptPromptRequestEventArgs args)
53+
{
54+
// The example uses dummy data intentionally. Replace the hard-coded string with a call to your AI API.
55+
args.Output = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.";
56+
}
57+
}
58+
````
59+
2060
## OnPromptRequest
2161

2262
The `OnPromptRequest` event fires when the user clicks on the **Generate** button within the Prompt view or retries a prompt from the Output view.
@@ -34,6 +74,12 @@ The event handler receives an argument of type [`AIPromptPromptRequestEventArgs`
3474

3575
> Do not use the `OnPromptRequest` event when [integrating the AIPrompt component with `Microsoft.Extensions.AI`](slug:common-features-microsoft-extensions-ai-integration). The `OnPromptRequest` event disables such integration.
3676
77+
## OnPromptRequestStop
78+
79+
The `OnPromptRequestStop` event fires when the user stops a prompt request by clicking the stop floating action button in the output view. This event allows you to handle the cancellation of an ongoing prompt request.
80+
81+
The event handler receives an `EventCallback` with no arguments.
82+
3783
## OnCommandExecute
3884

3985
The `OnCommandExecute` event fires when the user clicks on a command within the Commands view.
@@ -49,24 +95,9 @@ The event handler receives an argument of type [`AIPromptCommandExecuteEventArgs
4995
| `IsCancelled` | `bool` | Whether the event is cancelled and the built-in action is prevented. |
5096
| `OutputItem` | `AIPromptOutputItemDescriptor` | The output item. This property will be populated only when the user retries an existing output. See [`AIPromptOutputItemDescriptor`](slug:Telerik.Blazor.Components.AIPromptOutputItemDescriptor). |
5197

98+
## PromptChanged
5299

53-
## OnOutputRate
54-
55-
The `OnOutputRate` event fires when the user rates an output.
56-
57-
The event handler receives an argument of type [`AIPromptOutputRateEventArgs`](slug:Telerik.Blazor.Components.AIPromptOutputRateEventArgs). See the [example below](#example).
58-
59-
@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
60-
61-
| Property | Type | Description |
62-
| --- | --- | --- |
63-
| `OutputItem` | `AIPromptOutputItemDescriptor` | Specifies the output item that is being rated. See [`AIPromptOutputItemDescriptor`](slug:Telerik.Blazor.Components.AIPromptOutputItemDescriptor). |
64-
65-
## PromptTextChanged
66-
67-
The `PromptTextChanged` event fires when the user changes the prompt text. Use the event to update the AIPrompt's prompt when the `PromptText` parameter is set with one-way binding, otherwise, the user action will be ignored.
68-
69-
## See Also
100+
The `PromptChanged` event fires when the user changes the prompt text. Use the event to update the AIPrompt's prompt when the `Prompt` parameter is set with one-way binding, otherwise, the user action will be ignored.
70101

71102
## Example
72103

‎components/aiprompt/overview.md

Lines changed: 30 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -84,39 +84,13 @@ The AIPrompt component provides templates that enable developers to customize th
8484

8585
The various AIPrompt events allow you to implement custom functionality and handle user interactions with the component's ToolBar. [Read more about the AIPrompt events...](slug:aiprompt-events)
8686

87+
## Parameters and API
8788

88-
## AIPrompt Parameters
89+
The AIPrompt component provides a wide range of parameters and methods that let you customize its appearance, behavior, and integration with your application. You can configure built-in and custom views, toolbar items, commands, prompt suggestions, and more. The component also exposes methods for programmatic control, such as refreshing the UI or adding output items dynamically.
8990

90-
The table below lists the AIPrompt parameters. For a full list of the AIPrompt API members (parameters, methods, and events), check the [AIPrompt API Reference](slug:Telerik.Blazor.Components.TelerikAIPrompt).
91+
For a complete list of available parameters and methods, refer to the [AIPrompt API Reference](slug:Telerik.Blazor.Components.TelerikAIPrompt).
9192

92-
@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
93-
94-
| Parameter | Type and Default&nbsp;Value | Description |
95-
| --- | --- | --- |
96-
| `AIPromptViews` | `RenderFragment` | Allows control over the views of the content. Use it to set the visibility of a predefined view or to create custom views. If a render fragment is not provided, the AIPrompt will display its default views. |
97-
| `AIPromptToolBar` | `RenderFragment` | Any additional buttons that will be rendered within the ToolBar. This parameter will append the new items, rather than override buttons related to existing views. |
98-
| `Class` | `string` | The `class` attribute of the `<div class="k-prompt">` element. Use it to apply custom styles or [override the theme](slug:themes-override). |
99-
| `Commands` | `List<AIPromptCommandDescriptor>` | The predefined commands displayed within the Commands view. |
100-
| `Height` | `string` | The `height` style of the component in any [supported CSS unit](slug:common-features/dimensions). The default AIPrompt dimensions depend on the CSS theme. |
101-
| `PromptContext` | `string` | This text is appended to the prompt when sending the request. This is required in order to allow the component to work with external context, which is not visible in the prompt box.
102-
| `PromptText` | `string` | The value of the text within the prompt view. Use it when you need to add some form of transformation to the prompt. The parameter supports two-way binding. |
103-
| `PromptTextChanged` | `EventCallback<string>` | The handler called whenever the `PromptText` changes. |
104-
| `PromptSuggestions` | `List<string>` | The prompt suggestions displayed within the Prompt view. |
105-
| `PromptSuggestionItemTemplate` | `RenderFragment<string>` | The Prompt Suggestion Item template of the AIPrompt. |
106-
| `ShowOutputRating` | `bool` <br /> (`false`) | Controls the visibility of the rating buttons within the output card. |
107-
| `SystemPrompt` | `string` <br /> (See "Description" column) | Defines the system prompt that is passed to the [Microsoft `ChatMessage`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.ai.chatmessage) object constructor. <br /><br /> The default `SystemPrompt` value is: `"You are a helpful assistant designed to assist users. Your goal is to provide helpful, accurate, and contextually appropriate information in a clear and concise manner. Avoid discussing harmful, illegal, or inappropriate topics."`.
108-
| `Width` | `string` | The `width` style of the component in any [supported CSS unit](slug:common-features/dimensions). The default AIPrompt dimensions depend on the CSS theme. |
109-
110-
## AIPrompt Reference and Methods
111-
112-
The AIPrompt exposes methods for programmatic operation. To use them, define a reference to the component instance with the `@ref` directive attribute.
113-
114-
| Method | Description |
115-
| --- | --- |
116-
| `Refresh` | Re-renders the component. |
117-
| `AddOutput` | Insert a new output item to the AIPrompt. |
118-
119-
>caption AIPrompt reference and method usage
93+
To use component methods, define a reference to the AIPrompt instance with the `@ref` directive. For example:
12094

12195
````RAZOR
12296
<TelerikAIPrompt @ref="@AIPromptRef" OnPromptRequest="@HandlePromptRequest"></TelerikAIPrompt>
@@ -149,6 +123,32 @@ The AIPrompt exposes methods for programmatic operation. To use them, define a r
149123
}
150124
````
151125

126+
## SpeechToTextButton Integration
127+
128+
To integrate a built-in SpeechToTextButton in the AIPrompt component, set `EnableSpeechToText="true"`. Optionally, you can use the `<AIPromptSettings>` tag as a child of `<TelerikAIPrompt>`. Inside `<AIPromptSettings>`, you can define the `<AIPromptSpeechToTextButtonSettings>` tag to configure the appearance and behavior of the built-in SpeechToTextButton. For a complete list of available parameters, refer to the [AIPromptSpeechToTextButtonSettings API Reference](slug:Telerik.Blazor.Components.AIPromptSpeechToTextButtonSettings).
129+
130+
For advanced configuration options and more details about the SpeechToTextButton component, see the [SpeechToTextButton documentation](slug:speechtotextbutton-overview).
131+
132+
>caption Example of integrating the SpeechToTextButton in the AIPrompt component
133+
134+
````RAZOR.skip-repl
135+
<TelerikAIPrompt EnableSpeechToText="true" Prompt="@Prompt" PromptChanged="@OnPromptChanged">
136+
<AIPromptSettings>
137+
<AIPromptSpeechToTextButtonSettings FillMode="@ThemeConstants.Button.FillMode.Outline"
138+
Size="@ThemeConstants.Button.Size.Large"
139+
Rounded="@ThemeConstants.Button.Rounded.Full"
140+
ThemeColor="@ThemeConstants.Button.ThemeColor.Primary"
141+
MaxAlternatives="3" />
142+
</AIPromptSettings>
143+
</TelerikAIPrompt>
144+
145+
@code {
146+
private void OnPromptChanged(string prompt)
147+
{
148+
Prompt = prompt;
149+
}
150+
}
151+
````
152152

153153
## Next Steps
154154

‎upgrade/breaking-changes/10-0-0.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
title: 10.0.0
3+
description: Handle the changes in the 10.0.0 release of the Telerik UI for Blazor components.
4+
page_title: Breaking Changes in 10.0.0
5+
slug: changes-in-10-0-0
6+
position: 955
7+
---
8+
9+
# Breaking Changes in 10.0.0
10+
11+
## AIPrompt
12+
13+
The `OnOutputRate` event and the `ShowOutputRating` parameter are removed in version 10.0.0. To implement output rating or similar actions, use an output action and handle it through the [`OnOutputActionClick` event](slug:aiprompt-events#onoutputactionclick).
14+
15+
The **Retry** and **Copy** actions remain built-in, but you now need to define them as part of the `OutputActions` collection. For details on how to use output actions and handle user interaction, see the [OutputActionClick event example](slug:aiprompt-events#onoutputactionclick), which demonstrates how to configure the `OutputActions` collection, including the built-in **Copy** and **Retry** actions.

‎upgrade/breaking-changes/list.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ position: 0
99
# List of Telerik UI for Blazor Versions with Breaking Changes
1010

1111
This article lists the releases of the Telerik UI for Blazor product that introduce breaking changes. You may want to go through it when [upgrading](slug:upgrade-tutorial) to see whether you are affected.
12-
12+
* [10.0.0](slug:changes-in-10-0-0)
1313
* [9.0.0](slug:changes-in-9-0-0)
1414
* [8.0.0](slug:changes-in-8-0-0)
1515
* [7.0.0](slug:changes-in-7-0-0)

‎upgrade/rendering-changes/10-0-0.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: 10.0.0
3+
description: Handle the rendering changes in the 10.0.0 release of the Telerik UI for Blazor components.
4+
page_title: Rendering Changes in the 10.0.0 Release
5+
slug: rendering-changes-in-10-0-0
6+
position: 965
7+
---
8+
9+
# Rendering Changes in 10.0.0
10+
11+
## AIPrompt
12+
13+
The AIPrompt component now renders suggestion items using a new markup structure:
14+
15+
* The `k-prompt-suggestion` element is replaced by `k-suggestion`.
16+
* The `k-suggestion-group` element wraps all `k-suggestion` elements.
17+
18+
## See Also
19+
20+
* [Use best practices when overriding theme styles](slug:themes-override#best-practices)
21+
* [Breaking changes in Telerik UI for Blazor 10.0.0](slug:changes-in-10-0-0)

‎upgrade/rendering-changes/list.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ position: 0
1010

1111
As the Telerik UI for Blazor matures we will continuously optimize the HTML rendering and the usage of CSS classes. The rendering changes only affect the styling of the components if the application [overrides the built-in CSS styles](slug:themes-override) or uses an outdated [custom theme](slug:themes-customize). This article tracks the product versions with rendering changes.
1212

13+
* [10.0.0](slug:rendering-changes-in-10-0-0)
1314
* [7.0.0](slug:rendering-changes-in-7-0-0)
1415
* [6.0.0](slug:rendering-changes-in-6-0-0)
1516
* [4.6.0](slug:rendering-changes-in-4-6-0)

0 commit comments

Comments
 (0)