Skip to content

Commit ae91f19

Browse files
radkostanevradkostanev
authored
AIPrompt docs (#1883)
* docs(aiprompt): initial spike * docs(aiprompt): use correct toolbar casing * docs(aiprompt): syntax fixes * docs(aiprompt): address review * docs(aiprompt): address latest changes
1 parent 80ca3af commit ae91f19

File tree

10 files changed

+836
-0
lines changed

10 files changed

+836
-0
lines changed

‎_config.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -228,6 +228,9 @@ navigation:
228228
"*components/filemanager/data-binding":
229229
title: "Data Binding"
230230
position: 2
231+
"*components/aiprompt/views":
232+
title: "Views"
233+
position: 10
231234

232235
## List helpers directory names and order here, like this:
233236
"*appearance":
@@ -266,6 +269,8 @@ navigation:
266269
title: "Spreadsheet"
267270
"*gauges/arc":
268271
title: "Arc"
272+
"*aiprompt":
273+
title: "AIPrompt"
269274
"*appbar":
270275
title: "AppBar"
271276
"*autocomplete":
@@ -620,6 +625,7 @@ intro_columns:
620625
-
621626
title: "Interactivity and UX"
622627
items:
628+
"AIPrompt": "aiprompt-overview"
623629
"Loader": "loader-overview"
624630
"LoaderContainer": "loadercontainer-overview"
625631
"Skeleton": "skeleton-overview"

‎components/aiprompt/events.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
---
2+
title: Events
3+
page_title: AIPrompt - Events
4+
description: Explore the events generated by the AIPrompt for Blazor. Learn how to handle these events and implement custom functionality.
5+
slug: aiprompt-events
6+
tags: telerik,blazor,aiprompt,ai,prompt,events
7+
published: True
8+
position: 40
9+
---
10+
11+
# AIPrompt Events
12+
13+
This article explains the events available in the Telerik AIPrompt for Blazor:
14+
15+
* [`OnPromptRequest`](#onpromptrequest)
16+
* [`OnCommandExecute`](#oncommandexecute)
17+
* [`OnOutputRate`](#onoutputrate)
18+
* [`PromptTextChanged`](#promptexttchanged)
19+
20+
## OnPromptRequest
21+
22+
The `OnPromptRequest` event fires when the user clicks on the **Generate** button within the Prompt view or retries a prompt from the Output view.
23+
24+
The event handler receives an argument of type [`AIPromptPromptRequestEventArgs`](/blazor-ui/api/Telerik.Blazor.Components.AIPromptPromptRequestEventArgs). See the [example below](#example).
25+
26+
@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
27+
28+
| Property | Type | Description |
29+
| --- | --- | --- |
30+
| `Prompt` | `string` | The prompt text of the request. |
31+
| `Output` | `string` | The output of the request. The output is based on the prompt text. |
32+
| `IsCancelled` | `bool` | Whether the event is cancelled and the built-in action is prevented. |
33+
| `OutputItem` | `AIPromptOutputItem` | The output item. This property will be populated only when the user retries an existing output. See [`AIPromptOutputItem`](/blazor-ui/api/Telerik.Blazor.Components.AIPromptOutputItem). |
34+
35+
36+
## OnCommandExecute
37+
38+
The `OnCommandExecute` event fires when the user clicks on a command within the Commands view.
39+
40+
The event handler receives an argument of type [`AIPromptCommandDescriptorExecuteEventArgs`](/blazor-ui/api/Telerik.Blazor.Components.AIPromptCommandDescriptorExecuteEventArgs). See the [example below](#example).
41+
42+
@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
43+
44+
| Property | Type | Description |
45+
| --- | --- | --- |
46+
| `Command` | `AIPromptCommandDescriptor` | The executed command. |
47+
| `Output` | `string` | The output based on the executed command. |
48+
| `IsCancelled` | `bool` | Whether the event is cancelled and the built-in action is prevented. |
49+
| `OutputItem` | `AIPromptOutputItem` | The output item. This property will be populated only when the user retries an existing output. See [`AIPromptOutputItem`](/blazor-ui/api/Telerik.Blazor.Components.AIPromptOutputItem). |
50+
51+
52+
## OnOutputRate
53+
54+
The `OnOutputRate` event fires when the user rates an output.
55+
56+
The event handler receives an argument of type [`AIPromptOutputRateEventArgs`](/blazor-ui/api/Telerik.Blazor.Components.AIPromptOutputRateEventArgs). See the [example below](#example).
57+
58+
@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
59+
60+
| Property | Type | Description |
61+
| --- | --- | --- |
62+
| `OutputItem` | `AIPromptOutputItem` | Specifies the output item that is being rated. See [`AIPromptOutputItem`](/blazor-ui/api/Telerik.Blazor.Components.AIPromptOutputItem). |
63+
64+
## PromptTextChanged
65+
66+
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.
67+
68+
## See Also
69+
70+
## Example
71+
72+
>caption Using AIPrompt events
73+
74+
````CSHTML
75+
@* All AIPrompt events *@
76+
77+
<TelerikAIPrompt OnPromptRequest="@OnPromptRequestHandler"
78+
OnCommandExecute="@OnCommandExecuteHandler"
79+
OnOutputRate="@OnOutputRateHandler"
80+
PromptChanged="@OnPromptChanged"
81+
ShowOutputRating="true"
82+
Prompt="@Prompt"
83+
Commands="@PromptCommands">
84+
</TelerikAIPrompt>
85+
86+
@code {
87+
private string Prompt { get; set; }
88+
89+
private List<AIPromptCommandDescriptor> PromptCommands { get; set; } = new List<AIPromptCommandDescriptor>()
90+
{
91+
new AIPromptCommandDescriptor() { Id = "1", Title = "Correct Spelling and grammar", Icon = SvgIcon.SpellChecker },
92+
new AIPromptCommandDescriptor() { Id = "2", Title = "Change Tone", Icon = SvgIcon.TellAFriend,
93+
Children = new List<AIPromptCommandDescriptor>
94+
{
95+
new AIPromptCommandDescriptor() { Id = "3", Title = "Professional" },
96+
new AIPromptCommandDescriptor() { Id = "4", Title = "Conversational" },
97+
new AIPromptCommandDescriptor() { Id = "5", Title = "Humorous" },
98+
new AIPromptCommandDescriptor() { Id = "6", Title = "Empathic" },
99+
new AIPromptCommandDescriptor() { Id = "7", Title = "Academic" },
100+
}
101+
},
102+
};
103+
104+
private void OnPromptRequestHandler(AIPromptPromptRequestEventArgs args)
105+
{
106+
// The example uses dummy data intentionally. Replace the hard-coded string with a call to your AI API.
107+
args.Output = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Vel pretium lectus quam id leo in.";
108+
}
109+
110+
private void OnCommandExecuteHandler(AIPromptCommandExecuteEventArgs args)
111+
{
112+
// The example uses dummy data intentionally. Replace the hard-coded string with a call to your AI API.
113+
args.Output = "Nisl pretium fusce id velit ut tortor pretium. A pellentesque sit amet porttitor eget dolor. Lectus mauris ultrices eros in cursus turpis massa tincidunt.";
114+
}
115+
116+
private void OnOutputRateHandler(AIPromptOutputRateEventArgs args)
117+
{
118+
// The example uses dummy data intentionally. Replace the hard-coded string with a call to your AI API.
119+
}
120+
121+
private void OnPromptChanged(string prompt)
122+
{
123+
Prompt = prompt;
124+
}
125+
}
126+
127+
````
128+
129+
* [Live Demo: AIPrompt Overview](https://demos.telerik.com/blazor-ui/aiprompt/overview)

‎components/aiprompt/overview.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
---
2+
title: Overview
3+
page_title: AIPrompt Overview
4+
description: Discover the AIPrompt component for Blazor. Learn how to add the component to your app and explore its features like handling prompts and their outputs.
5+
slug: aiprompt-overview
6+
tags: telerik,blazor,aiprompt,ai,prompt
7+
published: True
8+
position: 0
9+
---
10+
11+
# Blazor AIPrompt Overview
12+
13+
The <a href = "https://www.telerik.com/blazor-ui/aiprompt" target="_blank">Blazor AIPrompt component</a> helps you write input (prompt) instructing the Generative AI to produce the desired response.
14+
15+
The component allows you to interact with the output from the AI and execute a set of predefined commands. Furthermore, the AIPrompt comes with three predefined views—Prompt, Output, and Command, as well as the option to define custom views. Users can navigate the views through the AIPrompt's ToolBar.
16+
17+
## Creating Blazor AIPrompt
18+
19+
1. Add the `<TelerikAIPrompt>` tag.
20+
1. Subscribe to the `OnPromptRequest` event that will fire whenever the user sends a prompt request. The handler expects an argument of type `AIPromptPromptRequestEventArgs`.
21+
1. (optional) Set the `Commands` parameter to a `List<AIPromptCommandDescriptor>`. If the parameter is not set, the AIPrompt will not render the Commands view.
22+
1. (optional) Subscribe to the `OnCommandExecute` event that will fire whenever the user executes a command. The handler expects an argument of type `AIPromptCommandDescriptorExecuteEventArgs`.
23+
24+
>caption Basic configuration of the Telerik AIPrompt
25+
26+
````CSHTML
27+
<TelerikAIPrompt OnPromptRequest="@HandlePromptRequest"
28+
OnCommandExecute="@HandleCommandExecute"
29+
Commands="@PromptCommands">
30+
</TelerikAIPrompt>
31+
32+
@code {
33+
private void HandlePromptRequest(AIPromptPromptRequestEventArgs args)
34+
{
35+
// The example uses dummy data intentionally. Replace the hard-coded string with a call to your AI API.
36+
args.Output = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.";
37+
}
38+
39+
private void HandleCommandExecute(AIPromptCommandExecuteEventArgs args)
40+
{
41+
// The example uses dummy data intentionally. Replace the hard-coded string with a call to your AI API.
42+
args.Output = "Vel pretium lectus quam id leo in. Nisl pretium fusce id velit ut tortor pretium.";
43+
}
44+
45+
private List<AIPromptCommandDescriptor> PromptCommands { get; set; } = new List<AIPromptCommandDescriptor>()
46+
{
47+
new AIPromptCommandDescriptor() { Id = "1", Title = "Correct spelling and grammar", Icon = FontIcon.SpellChecker },
48+
new AIPromptCommandDescriptor() { Id = "2", Title = "Change Tone", Icon = SvgIcon.TellAFriend,
49+
Children = new List<AIPromptCommandDescriptor>
50+
{
51+
new AIPromptCommandDescriptor() { Id = "3", Title = "Professional" },
52+
new AIPromptCommandDescriptor() { Id = "4", Title = "Conversational" },
53+
new AIPromptCommandDescriptor() { Id = "5", Title = "Humorous" },
54+
new AIPromptCommandDescriptor() { Id = "6", Title = "Empathic" },
55+
new AIPromptCommandDescriptor() { Id = "7", Title = "Academic" },
56+
}
57+
},
58+
new AIPromptCommandDescriptor() { Id = "8", Title = "Simplify", Icon = SvgIcon.MinWidth },
59+
new AIPromptCommandDescriptor() { Id = "9", Title = "Expand", Icon = SvgIcon.MaxWidth },
60+
};
61+
}
62+
````
63+
64+
65+
## ToolBar
66+
67+
The AIPrompt includes a toolbar with built-in buttons that activate the view they are related to. The component also exposes the option to add custom tools, which may be associated with arbitrary handlers. [Read more about the AIPrompt's ToolBar...]({%slug aiprompt-toolbar%})
68+
69+
70+
## Views
71+
72+
The AIPrompt component offers the Prompt, Output, and Commands views that relate to the current state of the prompt-response lifecycle. You can also customize the component through custom views. [Read more about the AIPrompt views...]({%slug aiprompt-views-overview%})
73+
74+
75+
## Templates
76+
77+
The AIPrompt component provides templates that enable developers to customize the rendering and appearance of the component. [Read more about the AIPrompt templates...]({%slug aiprompt-templates%})
78+
79+
80+
## Events
81+
82+
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%})
83+
84+
85+
## AIPrompt Parameters
86+
87+
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](/blazor-ui/api/Telerik.Blazor.Components.TelerikAIPrompt).
88+
89+
@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
90+
91+
| Parameter | Type and Default&nbsp;Value | Description |
92+
| --- | --- | --- |
93+
| `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. |
94+
| `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. |
95+
| `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. |
96+
| `PromptTextChanged` | `EventCallback<string>` | The handler called whenever the `PromptText` changes. |
97+
| `PromptSuggestions` | `List<string>` | The prompt suggestions displayed within the Prompt view. |
98+
| `PromptSuggestionItemTemplate` | `RenderFragment<string>` | The Prompt Suggestion Item template of the AIPrompt. |
99+
| `Commands` | `List<AIPromptCommandDescriptor>` | The predefined commands displayed within the Commands view. |
100+
| `ShowOutputRating` | `bool` <br /> (`false`) | Controls the visibility of the rating buttons within the output card. |
101+
| `OnPromptRequest` | `EventCallback<AIPromptPromptRequestEventArgs>` | The event handler called when the user requests an output for a given prompt. |
102+
| `OnCommandExecute` | `EventCallback<AIPromptCommandDescriptorExecuteEventArgs>` | The event handler called when a user clicks on a command within the Command view. |
103+
| `OnOutputRate` | `EventCallback<AIPromptOutputRateEventArgs>` | The event handler called when a user rates an output item. |
104+
| `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%}). |
105+
| `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. |
106+
| `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. |
107+
108+
## AIPrompt Reference and Methods
109+
110+
The AIPrompt exposes methods for programmatic operation. To use them, define a reference to the component instance with the `@ref` directive attribute.
111+
112+
| Method | Description |
113+
| --- | --- |
114+
| `Refresh` | Re-renders the component. |
115+
| `AddOutput` | Insert a new output item to the AIPrompt. |
116+
117+
>caption AIPrompt reference and method usage
118+
119+
````CSHTML
120+
<TelerikAIPrompt @ref="@AIPromptRef" OnPromptRequest="@HandlePromptRequest"></TelerikAIPrompt>
121+
<div style="margin-top: 2em;">
122+
<TelerikTextBox @bind-Value="@CustomPrompt"></TelerikTextBox>
123+
<TelerikButton OnClick="@ExternalGenerateHandler">Generate</TelerikButton>
124+
</div>
125+
126+
@code {
127+
private string CustomPrompt { get; set; }
128+
private TelerikAIPrompt AIPromptRef { get; set; }
129+
130+
private void ExternalGenerateHandler()
131+
{
132+
// The example uses dummy data intentionally. Replace the hard-coded string with a call to your AI API.
133+
AIPromptRef.AddOutput(
134+
output: "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
135+
title: "Generated from an external prompt",
136+
subtitle: string.Empty,
137+
prompt: CustomPrompt,
138+
commandId: null,
139+
openOutputView: true);
140+
}
141+
142+
private void HandlePromptRequest(AIPromptPromptRequestEventArgs args)
143+
{
144+
// The example uses dummy data intentionally. Replace the hard-coded string with a call to your AI API.
145+
args.Output = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.";
146+
}
147+
}
148+
````
149+
150+
151+
## Next Steps
152+
153+
* [Configure the AIPrompt ToolBar]({%slug aiprompt-toolbar%})
154+
* [Customize the AIPrompt Views]({%slug aiprompt-views-overview%})
155+
* [Make the AIPrompt Your Own through Custom Commands]({%slug aiprompt-views-commands%})
156+
* [Implement AIPrompt Views Templates]({%slug aiprompt-views-templates%})
157+
* [Implement AIPrompt Templates]({%slug aiprompt-templates%})
158+
* [Handle the AIPrompt Events]({%slug aiprompt-events%})
159+
160+
## See Also
161+
162+
* [Live Demo: AIPrompt](https://demos.telerik.com/blazor-ui/aiprompt/overview)
163+
* [AIPrompt API Reference](/blazor-ui/api/Telerik.Blazor.Components.TelerikAIPrompt)

‎components/aiprompt/templates.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
title: Templates
3+
page_title: AIPrompt Templates
4+
description: Discover the AIPrompt templates that let you customize the appearance of the component, for example, the rendering of the prompt suggestions.
5+
slug: aiprompt-templates
6+
tags: telerik,blazor,aiprompt,ai,prompt,templates
7+
published: True
8+
position: 30
9+
---
10+
11+
# AIPrompt Templates
12+
13+
The AIPrompt component provides the `PromptSuggestionItemTemplate` that allows you to change the appearance of the prompt suggestions made by the component.
14+
15+
>tip The AIPrompt component also implements [View templates]({%slug aiprompt-templates%}) that control the rendering of the Prompt, Output, and Command views.
16+
17+
The Prompt view of the AIPrompt renders any suggestions passed to the `PromptSuggestions` parameter in the form of elevated bubbles within a collapsible section. The `PromptSuggestionItemTemplate` allows you to control the rendering of individual suggestions.
18+
19+
>note By default, clicking on a suggestion will populate the prompt's input with the suggestion's value and also trigger a `PromptTextChanged` event. If you use the `PromptSuggestionItemTemplate`, you should also handle [any event]({%slug aiprompt-events%}) you deem necessary (such as `onclick`).
20+
21+
>caption Using the `PromptSuggestionItemTemplate` to alter the appearance of the suggestions
22+
23+
````CSHTML
24+
<TelerikAIPrompt @bind-Prompt="@Prompt" PromptSuggestions="@Suggestions">
25+
<PromptSuggestionItemTemplate>
26+
<div @onclick="@OnSuggestionClick" class="my-custom-suggestion-item">
27+
<TelerikSvgIcon Icon="@SvgIcon.Clipboard" />
28+
<span class="my-custom-suggestion-item-text">@context</span>
29+
</div>
30+
</PromptSuggestionItemTemplate>
31+
</TelerikAIPrompt>
32+
33+
<style>
34+
.my-custom-suggestion-item {
35+
display: flex;
36+
align-items: center;
37+
width: fit-content;
38+
padding: 0.5em 1.5em;
39+
border-radius: 20px;
40+
box-shadow: rgba(149, 157, 165, 0.2) 0px 8px 24px;
41+
cursor: pointer;
42+
transition: transform 0.2s ease-in-out;
43+
}
44+
45+
.my-custom-suggestion-item:hover {
46+
transform: scale(1.05);
47+
}
48+
49+
.my-custom-suggestion-item-text {
50+
padding-inline-start: 0.5em;
51+
}
52+
53+
</style>
54+
55+
@code {
56+
private string Prompt { get; set; }
57+
private TelerikAIPrompt AIPromptRef { get; set; }
58+
59+
private List<string> Suggestions { get; set; } = new List<string>()
60+
{
61+
"Explain quantum physics in simple terms.",
62+
"What are the three laws of thermodynamics?"
63+
};
64+
65+
private void OnSuggestionClick()
66+
{
67+
// handle suggestion click here.
68+
}
69+
}
70+
````
71+
72+
## See Also
73+
74+
* [Views Templates]({%slug aiprompt-views-templates%})

0 commit comments

Comments
 (0)