From d3a49d0a0bdfeadb14fab959c1ba45ac9836b20e Mon Sep 17 00:00:00 2001 From: radkostanev Date: Fri, 26 Jan 2024 15:25:51 +0200 Subject: [PATCH 1/5] docs(aiprompt): initial spike --- _config.yml | 6 + components/aiprompt/events.md | 130 +++++++++++++++++++ components/aiprompt/overview.md | 167 +++++++++++++++++++++++++ components/aiprompt/templates.md | 78 ++++++++++++ components/aiprompt/toolbar.md | 54 ++++++++ components/aiprompt/views/commands.md | 92 ++++++++++++++ components/aiprompt/views/output.md | 60 +++++++++ components/aiprompt/views/overview.md | 81 ++++++++++++ components/aiprompt/views/prompt.md | 44 +++++++ components/aiprompt/views/templates.md | 90 +++++++++++++ 10 files changed, 802 insertions(+) create mode 100644 components/aiprompt/events.md create mode 100644 components/aiprompt/overview.md create mode 100644 components/aiprompt/templates.md create mode 100644 components/aiprompt/toolbar.md create mode 100644 components/aiprompt/views/commands.md create mode 100644 components/aiprompt/views/output.md create mode 100644 components/aiprompt/views/overview.md create mode 100644 components/aiprompt/views/prompt.md create mode 100644 components/aiprompt/views/templates.md diff --git a/_config.yml b/_config.yml index f992aa6ecc..45ff73cf94 100644 --- a/_config.yml +++ b/_config.yml @@ -228,6 +228,9 @@ navigation: "*components/filemanager/data-binding": title: "Data Binding" position: 2 + "*components/aiprompt/views": + title: "Views" + position: 10 ## List helpers directory names and order here, like this: "*appearance": @@ -266,6 +269,8 @@ navigation: title: "Spreadsheet" "*gauges/arc": title: "Arc" + "*aiprompt": + title: "AIPrompt" "*appbar": title: "AppBar" "*autocomplete": @@ -620,6 +625,7 @@ intro_columns: - title: "Interactivity and UX" items: + "AIPrompt": "aiprompt-overview" "Loader": "loader-overview" "LoaderContainer": "loadercontainer-overview" "Skeleton": "skeleton-overview" diff --git a/components/aiprompt/events.md b/components/aiprompt/events.md new file mode 100644 index 0000000000..c40104ce95 --- /dev/null +++ b/components/aiprompt/events.md @@ -0,0 +1,130 @@ +--- +title: Events +page_title: AIPrompt - Events +description: Events in AIPrompt for Blazor. Learn how to handle the various events the component offers. +slug: aiprompt-events +tags: telerik,blazor,aiprompt,ai,prompt,events +published: True +position: 40 +--- + +# AIPrompt Events + +This article explains the events available in the Telerik AIPrompt for Blazor: + +* [`OnPromptRequest`](#onpromptrequest) +* [`OnCommandExecute`](#oncommandexecute) +* [`OnOutputRate`](#onoutputrate) +* [`PromptTextChanged`](#promptexttchanged) + +## OnPromptRequest + +The `OnPromptRequest` event fires when the user clicks on the generate button within the Prompt View or retries a prompt from the Output View. + +The event handler receives an argument of type [`AIPromptPromptRequestEventArgs`](/blazor-ui/api/Telerik.Blazor.Components.AIPromptPromptRequestEventArgs). See the [example below](#example). + +@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout) + +| Property | Type | Description | +| --- | --- | --- | +| `Prompt` | `string` | The prompt text of the request. | +| `Output` | `string` | The output of request based on the prompt text. | +| `IsCancelled` | `bool` | Whether the event is cancelled and the built-in action is prevented. | +| `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). | + + +## OnCommandExecute + +The `OnCommandExecute` event fires when the user clicks on a command within the Commands View. + +The event handler receives an argument of type [`AIPromptCommandDescriptorExecuteEventArgs`](/blazor-ui/api/Telerik.Blazor.Components.AIPromptCommandDescriptorExecuteEventArgs). See the [example below](#example). + +@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout) + +| Property | Type | Description | +| --- | --- | --- | +| `Command` | `AIPromptCommandDescriptor` | The executed command. | +| `ParentCommand` | `AIPromptCommandDescriptor` | The parent of the executed command. | +| `Output` | `string` | The output based on the executed command. | +| `IsCancelled` | `bool` | Whether the event is cancelled and the built-in action is prevented. | +| `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). | + + +## OnOutputRate + +The `OnOutputRate` event fires when the user rates an output. + +The event handler receives an argument of type [`AIPromptOutputRateEventArgs`](/blazor-ui/api/Telerik.Blazor.Components.AIPromptOutputRatingEventArgs). See the [example below](#example). + +@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout) + +| Property | Type | Description | +| --- | --- | --- | +| `OutputItem` | `AIPromptOutputItem` | Specifies the output item that is being rated. See [`AIPromptOutputItem`](/blazor-ui/api/Telerik.Blazor.Components.AIPromptOutputItem). | + +## PromptTextChanged + +The `PromptTextChanged` event fires when the user changes the prompt text. Use the event to update the AIPrompt prompt when the `PromptText` parameter is set with one-way binding, otherwise the user action will be ignored. + +## See Also + +## Example + +>caption Using AIPrompt events + +````CSHTML +@* All AIPrompt events *@ + + + + +@code { + private string Prompt { get; set; } + + private List PromptCommands { get; set; } = new List() + { + new AIPromptCommandDescriptor() { Id = "1", Title = "Correct Spelling and grammar", Icon = SvgIcon.SpellChecker }, + new AIPromptCommandDescriptor() { Id = "2", Title = "Change Tone", Icon = SvgIcon.TellAFriend, + Children = new List + { + new AIPromptCommandDescriptor() { Id = "3", Title = "Professional" }, + new AIPromptCommandDescriptor() { Id = "4", Title = "Conversational" }, + new AIPromptCommandDescriptor() { Id = "5", Title = "Humorous" }, + new AIPromptCommandDescriptor() { Id = "6", Title = "Empathic" }, + new AIPromptCommandDescriptor() { Id = "7", Title = "Academic" }, + } + }, + }; + + private void OnPromptRequestHandler(AIPromptPromptRequestEventArgs args) + { + // dummy data intentionally used. Replace the hard-coded string with a call to your AI API. + 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."; + } + + private void OnCommandExecuteHandler(AIPromptCommandExecuteEventArgs args) + { + // dummy data intentionally used. Replace the hard-coded string with a call to your AI API. + 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."; + } + + private void OnOutputRateHandler(AIPromptOutputRateEventArgs args) + { + // dummy data intentionally used. Replace the hard-coded string with a call to your AI API. + } + + private void OnPromptChanged(string prompt) + { + Prompt = prompt; + } +} + +```` + +* [Live Demo: AIPrompt Overview](https://demos.telerik.com/blazor-ui/aiprompt/overview) \ No newline at end of file diff --git a/components/aiprompt/overview.md b/components/aiprompt/overview.md new file mode 100644 index 0000000000..58bc510489 --- /dev/null +++ b/components/aiprompt/overview.md @@ -0,0 +1,167 @@ +--- +title: Overview +page_title: AIPrompt Overview +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. +slug: aiprompt-overview +tags: telerik,blazor,aiprompt,ai,prompt +published: True +position: 0 +--- + +# Blazor AIPrompt Overview + +The Blazor AIPrompt component helps you write input (prompt) instructing the Generative AI to generate the desired response. Furthermore, the component allows you to interact with the output from the AI, and execute a set of predefined commands. The AIPrompt comes with three predefined views - Prompt, Output, and Command, as well as the option to define custom views. Each view can be navigated through the AIPrompt's toolbar. + +## Creating Blazor AIPrompt + +To use a Telerik AIPrompt for Blazor: + +1. Add the `` tag. +1. Subscribe to the `OnPromptRequest` event that will fire whenever the user sends a prompt request. The handler expects an argument of type `AIPromptPromptRequestEventArgs`. +1. (optional)Set the `Commands` parameter to a `List`. If the parameter is not set, the AIPrompt will not render the Commands view. +1. (optional) Subscribe to the `OnCommandExecute` event that will fire whenever the user executes a command. The handler expects an argument of type `AIPromptCommandDescriptorExecuteEventArgs`. + +>caption Basic configuration of the Telerik AIPrompt + +````CSHTML + + + +@code { + private void HandlePromptRequest(AIPromptPromptRequestEventArgs args) + { + // dummy data intentionally used. Replace the hard-coded string with a call to your AI API. + args.Output = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."; + } + + private void HandleCommandExecute(AIPromptCommandExecuteEventArgs args) + { + // dummy data intentionally used. Replace the hard-coded string with a call to your AI API. + args.Output = "Vel pretium lectus quam id leo in. Nisl pretium fusce id velit ut tortor pretium."; + } + + private List PromptCommands { get; set; } = new List() + { + new AIPromptCommandDescriptor() { Id = "1", Title = "Correct spelling and grammar", Icon = FontIcon.SpellChecker }, + new AIPromptCommandDescriptor() { Id = "2", Title = "Change Tone", Icon = SvgIcon.TellAFriend, + Children = new List + { + new AIPromptCommandDescriptor() { Id = "3", Title = "Professional" }, + new AIPromptCommandDescriptor() { Id = "4", Title = "Conversational" }, + new AIPromptCommandDescriptor() { Id = "5", Title = "Humorous" }, + new AIPromptCommandDescriptor() { Id = "6", Title = "Empathic" }, + new AIPromptCommandDescriptor() { Id = "7", Title = "Academic" }, + } + }, + new AIPromptCommandDescriptor() { Id = "8", Title = "Simplify", Icon = SvgIcon.MinWidth }, + new AIPromptCommandDescriptor() { Id = "9", Title = "Expand", Icon = SvgIcon.MaxWidth }, + }; +} +```` + + +## Toolbar + +The [AIPrompt includes a toolbar with some built-in buttons]({%slug aiprompt-toolbar%}). When clicked, these tools activate the corresponding view they are related to. The component also exposes the option to add custom tools which may be associated with arbitrary handlers. + + +## Views + +The AIPrompt component offers [different views]({%slug aiprompt-views-overview%}) that relate to the current state of the prompt-response lifecycle. There is also the option to customize the component through custom views. The built-in views are: + +* Prompt View +* Output View +* Commands View + + +## Templates + +The [AIPrompt component provides templates]({%slug aiprompt-templates%}) to enable developers to customize the rendering and appearance of the component. + + +## Events + +The various [AIPrompt events]({%slug aiprompt-events%}) allow you to implement custom functionality and handle user interactions with the component's toolbar. + + +## AIPrompt Parameters + +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). + +@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout) + +| Parameter | Type and Default Value | Description | +| --- | --- | --- | +| `AIPromptViews` | `RenderFragment` | Allows control over the views of the content. Use it to set visibility of a predefined view or to create custom views. If a render fragment is not provided, the AIPrompt will display its default views. | +| `AIPromptToolbarItems` | `RenderFragment` | Any additional buttons that are to be rendered within the toolbar. This parameter will append the new items, rather than override buttons related to existing views. | +| `PromptText` | `string` | The value of the text within the prompt view. Use when you need to add some form of transformation to the prompt. The parameter supports two-way binding. | +| `PromptTextChanged` | `EventCallback` | The handler called whenever the `PromptText` changes. | +| `PromptSuggestions` | `List` | The prompt suggestions displayed within the prompt view. | +| `PromptSuggestionItemTemplate` | `RenderFragment` | The Prompt Suggestion Item template of the AIPrompt. | +| `Commands` | `List` | The predefined commands displayed within the commands view. | +| `ShowOutputRating` | `bool`
(`false`) | Controls the visibility of the rating buttons within the output card. | +| `OnPromptRequest` | `EventCallback` | The event handler called when the user requests an output for a given prompt. | +| `OnCommandExecute` | `EventCallback` | The event handler called when a user clicks on a command within the Command View. | +| `OnOutputRate` | `EventCallback` | The event handler called when a user rates an output item. | +| `Class` | `string` | The `class` attribute of the `
` element. Use it to apply custom styles or [override the theme]({%slug themes-override%}). | +| `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. | +| `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. | + +## AIPrompt Reference and Methods + +The AIPrompt exposes methods for programmatic operation. To use them, define a reference to the component instance with the `@ref` directive attribute. + +| Method | Description | +| --- | --- | +| `Refresh` | Re-renders the component. | +| `AddOutput` | Insert a new output item to the AIPrompt. | + +>caption AIPrompt reference and method usage + +````CSHTML + +
+ + Generate +
+ +@code { + private string CustomPrompt { get; set; } + private TelerikAIPrompt AIPromptRef { get; set; } + + private void ExternalGenerateHandler() + { + // dummy data intentionally used. Replace the hard-coded string with a call to your AI API. + AIPromptRef.AddOutput( + output: "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", + title: "Generated from an external prompt", + subtitle: string.Empty, + prompt: CustomPrompt, + commandId: null, + openOutputView: true); + } + + private void HandlePromptRequest(AIPromptPromptRequestEventArgs args) + { + // dummy data intentionally used. Replace the hard-coded string with a call to your AI API. + args.Output = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."; + } +} +```` + + +## Next Steps + +* [Configure the AIPrompt toolbar]({%slug aiprompt-toolbar%}) +* [Customize the AIPrompt views]({%slug aiprompt-views-overview%}) +* [Make the AIPrompt your own through custom commands]({%slug aiprompt-views-commands%}) +* [Implement AIPrompt templates]({%slug aiprompt-views-templates%}) +* [Implement AIPrompt templates]({%slug aiprompt-templates%}) +* [Handle the AIPrompt events]({%slug aiprompt-events%}) + +## See Also + +* [Live Demo: AIPrompt](https://demos.telerik.com/blazor-ui/aiprompt/overview) +* [AIPrompt API Reference](/blazor-ui/api/Telerik.Blazor.Components.TelerikAIPrompt) diff --git a/components/aiprompt/templates.md b/components/aiprompt/templates.md new file mode 100644 index 0000000000..86583487be --- /dev/null +++ b/components/aiprompt/templates.md @@ -0,0 +1,78 @@ +--- +title: Templates +page_title: AIPrompt Templates +description: Customize the appearance of the AIPrompt through its templates. +slug: aiprompt-templates +tags: telerik,blazor,aiprompt,ai,prompt,templates +published: True +position: 30 +--- + +# AIPrompt Views Templates + +This article explains the available templates of the AIPrompt component. For templating an entire view, refer to the [AIPrompt Views]({%slug aiprompt-templates%}) article. + +- [AIPrompt Views Templates](#aiprompt-views-templates) + - [PromptSuggestionItemTemplate](#promptsugestionitemtemplate) + + +## PromptSuggestionItemTemplate + +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. + +>note By default, clicking on a suggestion will populate the prompt's input with the suggestion's value. Such an interaction will also trigger a `PromptTextChanged` event. If you use the `PromptSuggestionItemTemplate`, you should also handle any event you deem necessary (such as `onclick`). + +>caption Use the `PromptSuggestionItemTemplate` to alter the appearance of the suggestions + +````CSHTML + + +
+ + @context +
+ + + + + +@code { + private string Prompt { get; set; } + private TelerikAIPrompt AIPromptRef { get; set; } + + private List Suggestions { get; set; } = new List() + { + "Explain quantum physics in simple terms.", + "What are the three laws of thermodynamics?" + }; + + private void OnSuggestionClick() + { + // handle suggestion click here. + } +} +```` + +## See Also + +* [Views Templates]({%slug aiprompt-views-templates%}) \ No newline at end of file diff --git a/components/aiprompt/toolbar.md b/components/aiprompt/toolbar.md new file mode 100644 index 0000000000..321f9521af --- /dev/null +++ b/components/aiprompt/toolbar.md @@ -0,0 +1,54 @@ +--- +title: Toolbar +page_title: AIPrompt - Toolbar +description: Configure and use the Blazor AIPrompt toolbar and its buttons. How to define custom toolbar buttons. +slug: aiprompt-toolbar +tags: telerik,blazor,aiprompt,ai,prompt,toolbar +published: True +position: 20 +--- + +# AIPrompt Toolbar + +The AIPrompt toolbar always renders buttons for the currently visible predefined views (Prompt, Output, and optionally, Command). These built-in buttons activate the appropriate view they represent. Any custom buttons will always appear after the view-related buttons. This article shows how to add custom tools to the AIPrompt's toolbar, which may invoke arbitrary commands or handlers. + + +## Custom Tools + +To define custom tools within the toolbar, use the `` tag, which is a standard Blazor `RenderFragment`. + +The example below omits any event handlers for brevity. Custom buttons are to be used for arbitrary logic which is not part of the AIPrompt component, thus feel free to attach the handlers you need. + +>caption Setting up the AIPrompt Toolbar + +````CSHTML + + + Custom Button + + + +@code { + private void HandlePromptRequest(AIPromptPromptRequestEventArgs args) + { + // handle the prompt request here. + } + + private void OnCustomButtonClick() + { + // handle the custom button click here. + } +} +```` + + +## Next Steps + +* [Customize the AIPrompt views]({%slug aiprompt-views-overview%}) +* [Implement AIPrompt templates]({%slug aiprompt-templates%}) +* [Handle AIPrompt events]({%slug aiprompt-events%}) + +## See Also + +* [Views Templates]({%slug aiprompt-views-templates%}) +* [Live Demo: AIPrompt Overview](https://demos.telerik.com/blazor-ui/aiprompt/overview) \ No newline at end of file diff --git a/components/aiprompt/views/commands.md b/components/aiprompt/views/commands.md new file mode 100644 index 0000000000..392a7947b3 --- /dev/null +++ b/components/aiprompt/views/commands.md @@ -0,0 +1,92 @@ +--- +title: Commands View +page_title: AIPrompt Commands View +description: Explore the AIPrompt Commands View. Learn how to define custom commands. +slug: aiprompt-views-commands +tags: telerik,blazor,aiprompt,ai,prompt,commands +published: True +position: 30 +--- + +# AIPrompt Commands View + +The Commands View displays a set of predefined commands, which the user can browse and execute. The commands are passed to the component through the `Commands` parameter, which expects a collection of type `List`. You can also organize commands in a hierarchy, through parent-child relationships. + +>note Parent commands cannot be directly executed, and only one level of nesting is supported. + +## AIPromptCommandDescriptor Parameters + +The following properties enable you to customize each command: + +@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout) + +| Parameter | Type | Description | +| ----------- | ----------- | ----------- | +| `Id` | `string` | The Id of the command. +| `Title` | `string` | The title of the command. Rendered as text within the Command View. | +| `Icon` | `object` | The [Telerik Font or SVG icon]({%slug common-features-icons%}) rendered before the title within the Command View. | +| `Children` | `List` | The nested commands(if any) of the command. | + +>caption Use the `Commands` parameter to pass a collection of predefined commands to the AIPrompt for Blazor + +````CSHTML + + + +@code { + private List PromptCommands { get; set; } = new List() + { + new AIPromptCommandDescriptor() { Id = "1", Title = "Correct Spelling and grammar", Icon = SvgIcon.SpellChecker }, + new AIPromptCommandDescriptor() { Id = "2", Title = "Change Tone", Icon = SvgIcon.TellAFriend, + Children = new List + { + new AIPromptCommandDescriptor() { Id = "3", Title = "Professional" }, + new AIPromptCommandDescriptor() { Id = "4", Title = "Conversational" }, + new AIPromptCommandDescriptor() { Id = "5", Title = "Humorous" }, + new AIPromptCommandDescriptor() { Id = "6", Title = "Empathic" }, + new AIPromptCommandDescriptor() { Id = "7", Title = "Academic" }, + } + }, + new AIPromptCommandDescriptor() { Id = "8", Title = "Change Formality", Icon = SvgIcon.ApplyFormat, + Children = new List + { + new AIPromptCommandDescriptor() { Id = "9", Title = "Casual" }, + new AIPromptCommandDescriptor() { Id = "10", Title = "Neutral" }, + new AIPromptCommandDescriptor() { Id = "11", Title = "Formal" }, + } + }, + new AIPromptCommandDescriptor() { Id = "12", Title = "Translate", Icon = SvgIcon.EditTools, + Children = new List + { + new AIPromptCommandDescriptor() { Id = "13", Title = "English" }, + new AIPromptCommandDescriptor() { Id = "14", Title = "Bulgarian" }, + new AIPromptCommandDescriptor() { Id = "15", Title = "Spanish" }, + } + }, + new AIPromptCommandDescriptor() { Id = "16", Title = "Simplify", Icon = SvgIcon.MinWidth }, + new AIPromptCommandDescriptor() { Id = "17", Title = "Expand", Icon = SvgIcon.MaxWidth }, + }; + + private void HandlePromptRequest(AIPromptPromptRequestEventArgs args) + { + // dummy data intentionally used. Replace the hard-coded string with a call to your AI API. + 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."; + } + + private void HandleCommandExecute(AIPromptCommandExecuteEventArgs args) + { + // dummy data intentionally used. Replace the hard-coded string with a call to your AI API. + 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."; + } +} +```` + +## See Also + + * [Live Demo: AIPrompt](https://demos.telerik.com/blazor-ui/aiprompt/overview) + * [Views Overview]({%slug aiprompt-views-overview%}) + * [Prompt View]({%slug aiprompt-views-prompt%}) + * [Output View]({%slug aiprompt-views-output%}) + * [Views Templates]({%slug aiprompt-views-templates%}) \ No newline at end of file diff --git a/components/aiprompt/views/output.md b/components/aiprompt/views/output.md new file mode 100644 index 0000000000..2c97e5f7fe --- /dev/null +++ b/components/aiprompt/views/output.md @@ -0,0 +1,60 @@ +--- +title: Output View +page_title: AIPrompt Output View +description: Explore the AIPrompt Output View. Learn how to handle output rating. +slug: aiprompt-views-output +tags: telerik,blazor,aiprompt,ai,prompt,output +published: True +position: 20 +--- + +# AIPrompt Output View + +The Output view shows the generated responses by the underlying AI service. Each response renders in its dedicated output card and provides two options to the user - to copy the content of the response or to retry the request. + +If the `ShowOutputRating` is enabled on the component level, the output card will also feature two additional options - to upvote and downvote the response. This interaction can be handled through the `OnOutputRate` event. For more information on how to handle the event, refer to the [AIPrompt events]({%slug aiprompt-events%}) article. + +By default, the Output View is rendered and is part of the predefined views. However, if you provide a render fragment of type `AIPromptViews` to the `TelerikAIPrompt` tag, you override the default rendering, meaning you should explicitly add `AIPromptOutputView` tag within it. The Output View is activated through interaction - once the user fills out a prompt within the Prompt View and requests a response, the Output View will become active. + +>caption Use the `ButtonText` and `ButtonIcon` to alter the appearance of view button. + +````CSHTML + + + + + + + +@code { + private string Prompt { get; set; } +} +```` + +>caption Use the `ShowOutputRating` to include visuals related to upvoting or downvoting a specific output. + +````CSHTML + + + + + + + +@code { + private string Prompt { get; set; } + + private void OnOutputRateHandler(AIPromptOutputRatingEventArgs args) + { + // Handle the output rate event here + } +} +```` + +## See Also + + * [Live Demo: AIPrompt](https://demos.telerik.com/blazor-ui/aiprompt/overview) + * [Views Overview]({%slug aiprompt-views-overview%}) + * [Prompt View]({%slug aiprompt-views-prompt%}) + * [Commands View]({%slug aiprompt-views-commands%}) + * [Views Templates]({%slug aiprompt-views-templates%}) \ No newline at end of file diff --git a/components/aiprompt/views/overview.md b/components/aiprompt/views/overview.md new file mode 100644 index 0000000000..122acc8a1b --- /dev/null +++ b/components/aiprompt/views/overview.md @@ -0,0 +1,81 @@ +--- +title: Overview +page_title: AIPrompt - Views Overview +description: Views basics in the AIPrompt for Blazor. +slug: aiprompt-views-overview +tags: telerik,blazor,aiprompt,ai,prompt,view,overview +published: True +position: 0 +--- + +# AIPrompt Views + +The AIPrompt component provides three different predefined views. There is also the option to define custom views. Through interaction with the component, the user can change the currently active view. + +The available built-in views are: + +* [Prompt View]({%slug aiprompt-views-prompt%}) +* [Output View]({%slug aiprompt-views-output%}) +* [Commands View]({%slug aiprompt-views-commands%}) + +## Parameters + +>caption The AIPrompt views provides various parameters that allow you to configure the component: + +@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout) + +| Parameter | Type | Description | +| --- | --- | --- | +| `ButtonText` | `string` | The text rendered within the toolbar button associated with the view. | +| `ButtonIcon` | `object` | The [Telerik Font or SVG icon]({%slug common-features-icons%}) rendered within the toolbar button associated with the view. | +| `ViewTemplate` | `RenderFragment` | The ViewTemplate allows you to control the rendering of the content of the view. Read more in the [Templates]({%slug aiprompt-views-templates%}#viewtemplate) article. | +| `FooterTemplate` | `RenderFragment` | The FooterTemplate allows you to control the rendering of the footer of the view. Read more in the [Templates]({%slug aiprompt-views-templates%}#footertemplate) article. | + +>caption By default, the AIPrompt will always render both the Prompt and the Output view. The Commands view will be rendered only if a custom set of commands has been passed through the `Commands` parameter. + + +````CSHTML +@* The user can only navigate between the Prompt and Output views - the Commands view, for example, will not be rendered, as no commands has been passed to the `Commands` parameter. *@ + + + +@code { + private void HandlePromptRequest(AIPromptPromptRequestEventArgs args) + { + // dummy data intentionally used. Replace the hard-coded string with a call to your AI API. + args.Output = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."; + } +} +```` + +>caption Use the `ButtonText` and `ButtonIcon` parameters to customize the appearance of the toolbar buttons associated with the predefined views. + + +````CSHTML +@* The example showcases how to customize the appearance of the toolbar through the `ButtonText` and `ButtonIcon` parameters. *@ + + + + + + + + + +@code { + private void HandlePromptRequest(AIPromptPromptRequestEventArgs args) + { + // dummy data intentionally used. Replace the hard-coded string with a call to your AI API. + 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."; + } +} +```` + +## See Also + + * [Live Demo: AIPrompt](https://demos.telerik.com/blazor-ui/aiprompt/overview) + * [Prompt View]({%slug aiprompt-views-prompt%}) + * [Output View]({%slug aiprompt-views-output%}) + * [Commands View]({%slug aiprompt-views-commands%}) + * [Views Templates]({%slug aiprompt-views-templates%}) + diff --git a/components/aiprompt/views/prompt.md b/components/aiprompt/views/prompt.md new file mode 100644 index 0000000000..2153571fd3 --- /dev/null +++ b/components/aiprompt/views/prompt.md @@ -0,0 +1,44 @@ +--- +title: Prompt View +page_title: AIPrompt Prompt View +description: Explore the AIPrompt Prompt View. Learn how to pass a set of prompt suggestions. +slug: aiprompt-views-prompt +tags: telerik,blazor,aiprompt,prompt +published: True +position: 10 +--- + +# AIPrompt Prompt View + +The Prompt View features the prompt input, where users can type their query. It also contains a button to trigger a response request. + +Additionally, the Prompt View can contain prompt suggestions related to the prompt itself through the `PromptSuggestions` parameter. The user can select any of the available suggestions, which in turn will populate the prompt input with the selected suggestion. This interaction will not trigger a response request right away - the user can modify the suggestion first. + +>caption Use the `PromptSuggestions` to display a set of predefined prompts or hints. + +````CSHTML + + +@code { + private List PromptSuggestions { get; set; } = new List() + { + "Act as a marketing specialist and content writer and write a compelling [type of text] that speaks directly to my [ideal customer persona] and encourages them to take [desired action] on my [website/product].", + "I'm looking for a [type of text] that will convince [ideal customer persona] to sign up for my [program/subscription] by explaining the value it brings and the benefits they'll receive.", + "Write a Twitter thread idea that will both go viral and attract high-quality leads for my [product/service] with a strong call-to-action and compelling visuals." + }; + + private void HandlePromptRequest(AIPromptPromptRequestEventArgs args) + { + // dummy data intentionally used. Replace the hard-coded string with a call to your AI API. + args.Output = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."; + } +} +```` + +## See Also + + * [Live Demo: AIPrompt](https://demos.telerik.com/blazor-ui/aiprompt/overview) + * [Views Overview]({%slug aiprompt-views-overview%}) + * [Prompt View]({%slug aiprompt-views-prompt%}) + * [Output View]({%slug aiprompt-views-output%}) + * [Views Templates]({%slug aiprompt-views-templates%}) \ No newline at end of file diff --git a/components/aiprompt/views/templates.md b/components/aiprompt/views/templates.md new file mode 100644 index 0000000000..96fdfa89b3 --- /dev/null +++ b/components/aiprompt/views/templates.md @@ -0,0 +1,90 @@ +--- +title: Templates +page_title: AIPrompt Views Templates +description: View Templates in AIPrompt for Blazor. Learn how to customize the appearance of individual views. +slug: aiprompt-views-templates +tags: telerik,blazor,aiprompt,ai,prompt,templates +published: True +position: 40 +--- + +# AIPrompt Views Templates + +This article explains the available templates for the Views of the AIPrompt for Blazor. + +- [AIPrompt Views Templates](#aiprompt-views-templates) + - [ViewTemplate](#viewtemplate) + - [FooterTemplate](#footertemplate) + + +## ViewTemplate + +The `ViewTemplate` allows you to control the rendering of view's content. You can define it for each of the predefined Views: + +>caption Use the ViewTemplate to alter the appearance of the prompt view + +````CSHTML + + + + + + + + + + + + +@code { + private TelerikAIPrompt AIPromptRef { get; set; } + + private string Prompt { get; set; } +} +```` + +## FooterTemplate + +The `FooterTemplate` allows you to control the rendering of the footer within individual views. + +>caption Use the FooterTemplate to define a custom button. + +````CSHTML + + + + + Generate + + + + + + + +@code { + private TelerikAIPrompt AIPromptRef { get; set; } + + private string Prompt { get; set; } + + private void HandlePromptRequest() + { + // dummy data intentionally used. Replace the hard-coded string with a call to your AI API. + AIPromptRef.AddOutput( + output: "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", + title: "Generated response", + subtitle: string.Empty, + prompt: Prompt, + commandId: null, + openOutputView: true); + } +} +```` + +## See Also + + * [Live Demo: AIPrompt](https://demos.telerik.com/blazor-ui/aiprompt/overview) + * [Views Overview]({%slug aiprompt-views-overview%}) + * [Prompt View]({%slug aiprompt-views-prompt%}) + * [Output View]({%slug aiprompt-views-output%}) + * [Commands View]({%slug aiprompt-views-commands%}) \ No newline at end of file From bd03990ead43588bddc69bc3ab46a6e05b7c042f Mon Sep 17 00:00:00 2001 From: radkostanev Date: Fri, 26 Jan 2024 16:00:16 +0200 Subject: [PATCH 2/5] docs(aiprompt): use correct toolbar casing --- components/aiprompt/overview.md | 2 +- components/aiprompt/toolbar.md | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/components/aiprompt/overview.md b/components/aiprompt/overview.md index 58bc510489..073499660a 100644 --- a/components/aiprompt/overview.md +++ b/components/aiprompt/overview.md @@ -95,7 +95,7 @@ The table below lists the AIPrompt parameters. For a full list of the AIPrompt A | Parameter | Type and Default Value | Description | | --- | --- | --- | | `AIPromptViews` | `RenderFragment` | Allows control over the views of the content. Use it to set visibility of a predefined view or to create custom views. If a render fragment is not provided, the AIPrompt will display its default views. | -| `AIPromptToolbarItems` | `RenderFragment` | Any additional buttons that are to be rendered within the toolbar. This parameter will append the new items, rather than override buttons related to existing views. | +| `AIPromptToolBarItems` | `RenderFragment` | Any additional buttons that are to be rendered within the toolbar. This parameter will append the new items, rather than override buttons related to existing views. | | `PromptText` | `string` | The value of the text within the prompt view. Use when you need to add some form of transformation to the prompt. The parameter supports two-way binding. | | `PromptTextChanged` | `EventCallback` | The handler called whenever the `PromptText` changes. | | `PromptSuggestions` | `List` | The prompt suggestions displayed within the prompt view. | diff --git a/components/aiprompt/toolbar.md b/components/aiprompt/toolbar.md index 321f9521af..d62b0dfeb3 100644 --- a/components/aiprompt/toolbar.md +++ b/components/aiprompt/toolbar.md @@ -8,24 +8,24 @@ published: True position: 20 --- -# AIPrompt Toolbar +# AIPrompt ToolBar The AIPrompt toolbar always renders buttons for the currently visible predefined views (Prompt, Output, and optionally, Command). These built-in buttons activate the appropriate view they represent. Any custom buttons will always appear after the view-related buttons. This article shows how to add custom tools to the AIPrompt's toolbar, which may invoke arbitrary commands or handlers. ## Custom Tools -To define custom tools within the toolbar, use the `` tag, which is a standard Blazor `RenderFragment`. +To define custom tools within the toolbar, use the `` tag, which is a standard Blazor `RenderFragment`. The example below omits any event handlers for brevity. Custom buttons are to be used for arbitrary logic which is not part of the AIPrompt component, thus feel free to attach the handlers you need. ->caption Setting up the AIPrompt Toolbar +>caption Setting up the AIPrompt ToolBar ````CSHTML - - Custom Button - + + Custom Button + @code { From f60e4fa7534fec12f54c9c7aa3a3f503f128b893 Mon Sep 17 00:00:00 2001 From: radkostanev Date: Mon, 29 Jan 2024 12:50:26 +0200 Subject: [PATCH 3/5] docs(aiprompt): syntax fixes --- components/aiprompt/events.md | 2 +- components/aiprompt/toolbar.md | 6 +++--- components/aiprompt/views/output.md | 2 +- components/aiprompt/views/overview.md | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/components/aiprompt/events.md b/components/aiprompt/events.md index c40104ce95..71fee3adbb 100644 --- a/components/aiprompt/events.md +++ b/components/aiprompt/events.md @@ -54,7 +54,7 @@ The event handler receives an argument of type [`AIPromptCommandDescriptorExecut The `OnOutputRate` event fires when the user rates an output. -The event handler receives an argument of type [`AIPromptOutputRateEventArgs`](/blazor-ui/api/Telerik.Blazor.Components.AIPromptOutputRatingEventArgs). See the [example below](#example). +The event handler receives an argument of type [`AIPromptOutputRateEventArgs`](/blazor-ui/api/Telerik.Blazor.Components.AIPromptOutputRateEventArgs). See the [example below](#example). @[template](/_contentTemplates/common/parameters-table-styles.md#table-layout) diff --git a/components/aiprompt/toolbar.md b/components/aiprompt/toolbar.md index d62b0dfeb3..ec86c8b87e 100644 --- a/components/aiprompt/toolbar.md +++ b/components/aiprompt/toolbar.md @@ -23,9 +23,9 @@ The example below omits any event handlers for brevity. Custom buttons are to be ````CSHTML - - Custom Button - + + Custom Button + @code { diff --git a/components/aiprompt/views/output.md b/components/aiprompt/views/output.md index 2c97e5f7fe..64f725e8e0 100644 --- a/components/aiprompt/views/output.md +++ b/components/aiprompt/views/output.md @@ -44,7 +44,7 @@ By default, the Output View is rendered and is part of the predefined views. How @code { private string Prompt { get; set; } - private void OnOutputRateHandler(AIPromptOutputRatingEventArgs args) + private void OnOutputRateHandler(AIPromptOutputRateEventArgs args) { // Handle the output rate event here } diff --git a/components/aiprompt/views/overview.md b/components/aiprompt/views/overview.md index 122acc8a1b..601c58b48d 100644 --- a/components/aiprompt/views/overview.md +++ b/components/aiprompt/views/overview.md @@ -58,7 +58,7 @@ The available built-in views are: - + From 932c5f8e36084012b5127d3b5769850afffe9b5b Mon Sep 17 00:00:00 2001 From: radkostanev Date: Mon, 29 Jan 2024 16:44:18 +0200 Subject: [PATCH 4/5] docs(aiprompt): address review --- components/aiprompt/events.md | 16 ++++---- components/aiprompt/overview.md | 54 ++++++++++++-------------- components/aiprompt/templates.md | 18 ++++----- components/aiprompt/toolbar.md | 13 ++++--- components/aiprompt/views/commands.md | 18 ++++----- components/aiprompt/views/output.md | 10 ++--- components/aiprompt/views/overview.md | 18 ++++----- components/aiprompt/views/prompt.md | 12 +++--- components/aiprompt/views/templates.md | 23 ++++++----- 9 files changed, 87 insertions(+), 95 deletions(-) diff --git a/components/aiprompt/events.md b/components/aiprompt/events.md index 71fee3adbb..eb60a1581f 100644 --- a/components/aiprompt/events.md +++ b/components/aiprompt/events.md @@ -1,7 +1,7 @@ --- title: Events page_title: AIPrompt - Events -description: Events in AIPrompt for Blazor. Learn how to handle the various events the component offers. +description: Explore the events generated by the AIPrompt for Blazor. Learn how to handle these events and implement custom functionality. slug: aiprompt-events tags: telerik,blazor,aiprompt,ai,prompt,events published: True @@ -19,7 +19,7 @@ This article explains the events available in the Telerik AIPrompt for Blazor: ## OnPromptRequest -The `OnPromptRequest` event fires when the user clicks on the generate button within the Prompt View or retries a prompt from the Output View. +The `OnPromptRequest` event fires when the user clicks on the **Generate** button within the Prompt view or retries a prompt from the Output view. The event handler receives an argument of type [`AIPromptPromptRequestEventArgs`](/blazor-ui/api/Telerik.Blazor.Components.AIPromptPromptRequestEventArgs). See the [example below](#example). @@ -28,14 +28,14 @@ The event handler receives an argument of type [`AIPromptPromptRequestEventArgs` | Property | Type | Description | | --- | --- | --- | | `Prompt` | `string` | The prompt text of the request. | -| `Output` | `string` | The output of request based on the prompt text. | +| `Output` | `string` | The output of the request. The output is based on the prompt text. | | `IsCancelled` | `bool` | Whether the event is cancelled and the built-in action is prevented. | | `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). | ## OnCommandExecute -The `OnCommandExecute` event fires when the user clicks on a command within the Commands View. +The `OnCommandExecute` event fires when the user clicks on a command within the Commands view. The event handler receives an argument of type [`AIPromptCommandDescriptorExecuteEventArgs`](/blazor-ui/api/Telerik.Blazor.Components.AIPromptCommandDescriptorExecuteEventArgs). See the [example below](#example). @@ -64,7 +64,7 @@ The event handler receives an argument of type [`AIPromptOutputRateEventArgs`](/ ## PromptTextChanged -The `PromptTextChanged` event fires when the user changes the prompt text. Use the event to update the AIPrompt prompt when the `PromptText` parameter is set with one-way binding, otherwise the user action will be ignored. +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. ## See Also @@ -104,19 +104,19 @@ The `PromptTextChanged` event fires when the user changes the prompt text. Use t private void OnPromptRequestHandler(AIPromptPromptRequestEventArgs args) { - // dummy data intentionally used. Replace the hard-coded string with a call to your AI API. + // The example uses dummy data intentionally. Replace the hard-coded string with a call to your AI API. 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."; } private void OnCommandExecuteHandler(AIPromptCommandExecuteEventArgs args) { - // dummy data intentionally used. Replace the hard-coded string with a call to your AI API. + // The example uses dummy data intentionally. Replace the hard-coded string with a call to your AI API. 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."; } private void OnOutputRateHandler(AIPromptOutputRateEventArgs args) { - // dummy data intentionally used. Replace the hard-coded string with a call to your AI API. + // The example uses dummy data intentionally. Replace the hard-coded string with a call to your AI API. } private void OnPromptChanged(string prompt) diff --git a/components/aiprompt/overview.md b/components/aiprompt/overview.md index 073499660a..97ba398527 100644 --- a/components/aiprompt/overview.md +++ b/components/aiprompt/overview.md @@ -10,15 +10,15 @@ position: 0 # Blazor AIPrompt Overview -The Blazor AIPrompt component helps you write input (prompt) instructing the Generative AI to generate the desired response. Furthermore, the component allows you to interact with the output from the AI, and execute a set of predefined commands. The AIPrompt comes with three predefined views - Prompt, Output, and Command, as well as the option to define custom views. Each view can be navigated through the AIPrompt's toolbar. +The Blazor AIPrompt component helps you write input (prompt) instructing the Generative AI to produce the desired response. -## Creating Blazor AIPrompt +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. -To use a Telerik AIPrompt for Blazor: +## Creating Blazor AIPrompt 1. Add the `` tag. 1. Subscribe to the `OnPromptRequest` event that will fire whenever the user sends a prompt request. The handler expects an argument of type `AIPromptPromptRequestEventArgs`. -1. (optional)Set the `Commands` parameter to a `List`. If the parameter is not set, the AIPrompt will not render the Commands view. +1. (optional) Set the `Commands` parameter to a `List`. If the parameter is not set, the AIPrompt will not render the Commands view. 1. (optional) Subscribe to the `OnCommandExecute` event that will fire whenever the user executes a command. The handler expects an argument of type `AIPromptCommandDescriptorExecuteEventArgs`. >caption Basic configuration of the Telerik AIPrompt @@ -32,13 +32,13 @@ To use a Telerik AIPrompt for Blazor: @code { private void HandlePromptRequest(AIPromptPromptRequestEventArgs args) { - // dummy data intentionally used. Replace the hard-coded string with a call to your AI API. + // The example uses dummy data intentionally. Replace the hard-coded string with a call to your AI API. args.Output = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."; } private void HandleCommandExecute(AIPromptCommandExecuteEventArgs args) { - // dummy data intentionally used. Replace the hard-coded string with a call to your AI API. + // The example uses dummy data intentionally. Replace the hard-coded string with a call to your AI API. args.Output = "Vel pretium lectus quam id leo in. Nisl pretium fusce id velit ut tortor pretium."; } @@ -62,28 +62,24 @@ To use a Telerik AIPrompt for Blazor: ```` -## Toolbar +## ToolBar -The [AIPrompt includes a toolbar with some built-in buttons]({%slug aiprompt-toolbar%}). When clicked, these tools activate the corresponding view they are related to. The component also exposes the option to add custom tools which may be associated with arbitrary handlers. +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%}) ## Views -The AIPrompt component offers [different views]({%slug aiprompt-views-overview%}) that relate to the current state of the prompt-response lifecycle. There is also the option to customize the component through custom views. The built-in views are: - -* Prompt View -* Output View -* Commands View +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%}) ## Templates -The [AIPrompt component provides templates]({%slug aiprompt-templates%}) to enable developers to customize the rendering and appearance of the component. +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%}) ## Events -The various [AIPrompt events]({%slug aiprompt-events%}) allow you to implement custom functionality and handle user interactions with the component's toolbar. +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%}) ## AIPrompt Parameters @@ -94,16 +90,16 @@ The table below lists the AIPrompt parameters. For a full list of the AIPrompt A | Parameter | Type and Default Value | Description | | --- | --- | --- | -| `AIPromptViews` | `RenderFragment` | Allows control over the views of the content. Use it to set visibility of a predefined view or to create custom views. If a render fragment is not provided, the AIPrompt will display its default views. | -| `AIPromptToolBarItems` | `RenderFragment` | Any additional buttons that are to be rendered within the toolbar. This parameter will append the new items, rather than override buttons related to existing views. | -| `PromptText` | `string` | The value of the text within the prompt view. Use when you need to add some form of transformation to the prompt. The parameter supports two-way binding. | +| `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. | +| `AIPromptToolBarItems` | `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. | +| `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. | | `PromptTextChanged` | `EventCallback` | The handler called whenever the `PromptText` changes. | -| `PromptSuggestions` | `List` | The prompt suggestions displayed within the prompt view. | +| `PromptSuggestions` | `List` | The prompt suggestions displayed within the Prompt view. | | `PromptSuggestionItemTemplate` | `RenderFragment` | The Prompt Suggestion Item template of the AIPrompt. | -| `Commands` | `List` | The predefined commands displayed within the commands view. | +| `Commands` | `List` | The predefined commands displayed within the Commands view. | | `ShowOutputRating` | `bool`
(`false`) | Controls the visibility of the rating buttons within the output card. | | `OnPromptRequest` | `EventCallback` | The event handler called when the user requests an output for a given prompt. | -| `OnCommandExecute` | `EventCallback` | The event handler called when a user clicks on a command within the Command View. | +| `OnCommandExecute` | `EventCallback` | The event handler called when a user clicks on a command within the Command view. | | `OnOutputRate` | `EventCallback` | The event handler called when a user rates an output item. | | `Class` | `string` | The `class` attribute of the `
` element. Use it to apply custom styles or [override the theme]({%slug themes-override%}). | | `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. | @@ -133,7 +129,7 @@ The AIPrompt exposes methods for programmatic operation. To use them, define a r private void ExternalGenerateHandler() { - // dummy data intentionally used. Replace the hard-coded string with a call to your AI API. + // The example uses dummy data intentionally. Replace the hard-coded string with a call to your AI API. AIPromptRef.AddOutput( output: "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", title: "Generated from an external prompt", @@ -145,7 +141,7 @@ The AIPrompt exposes methods for programmatic operation. To use them, define a r private void HandlePromptRequest(AIPromptPromptRequestEventArgs args) { - // dummy data intentionally used. Replace the hard-coded string with a call to your AI API. + // The example uses dummy data intentionally. Replace the hard-coded string with a call to your AI API. args.Output = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."; } } @@ -154,12 +150,12 @@ The AIPrompt exposes methods for programmatic operation. To use them, define a r ## Next Steps -* [Configure the AIPrompt toolbar]({%slug aiprompt-toolbar%}) -* [Customize the AIPrompt views]({%slug aiprompt-views-overview%}) -* [Make the AIPrompt your own through custom commands]({%slug aiprompt-views-commands%}) -* [Implement AIPrompt templates]({%slug aiprompt-views-templates%}) -* [Implement AIPrompt templates]({%slug aiprompt-templates%}) -* [Handle the AIPrompt events]({%slug aiprompt-events%}) +* [Configure the AIPrompt ToolBar]({%slug aiprompt-toolbar%}) +* [Customize the AIPrompt Views]({%slug aiprompt-views-overview%}) +* [Make the AIPrompt Your Own through Custom Commands]({%slug aiprompt-views-commands%}) +* [Implement AIPrompt Views Templates]({%slug aiprompt-views-templates%}) +* [Implement AIPrompt Templates]({%slug aiprompt-templates%}) +* [Handle the AIPrompt Events]({%slug aiprompt-events%}) ## See Also diff --git a/components/aiprompt/templates.md b/components/aiprompt/templates.md index 86583487be..74a9355ca8 100644 --- a/components/aiprompt/templates.md +++ b/components/aiprompt/templates.md @@ -1,28 +1,24 @@ --- title: Templates page_title: AIPrompt Templates -description: Customize the appearance of the AIPrompt through its templates. +description: Discover the AIPrompt templates that let you customize the appearance of the component, for example, the rendering of the prompt suggestions. slug: aiprompt-templates tags: telerik,blazor,aiprompt,ai,prompt,templates published: True position: 30 --- -# AIPrompt Views Templates +# AIPrompt Templates -This article explains the available templates of the AIPrompt component. For templating an entire view, refer to the [AIPrompt Views]({%slug aiprompt-templates%}) article. +The AIPrompt component provides the `PromptSuggestionItemTemplate` that allows you to change the appearance of the prompt suggestions made by the component. -- [AIPrompt Views Templates](#aiprompt-views-templates) - - [PromptSuggestionItemTemplate](#promptsugestionitemtemplate) +>tip The AIPrompt component also implements [View templates]({%slug aiprompt-templates%}) that control the rendering of the Prompt, Output, and Command views. +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. -## PromptSuggestionItemTemplate +>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`). -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. - ->note By default, clicking on a suggestion will populate the prompt's input with the suggestion's value. Such an interaction will also trigger a `PromptTextChanged` event. If you use the `PromptSuggestionItemTemplate`, you should also handle any event you deem necessary (such as `onclick`). - ->caption Use the `PromptSuggestionItemTemplate` to alter the appearance of the suggestions +>caption Using the `PromptSuggestionItemTemplate` to alter the appearance of the suggestions ````CSHTML diff --git a/components/aiprompt/toolbar.md b/components/aiprompt/toolbar.md index ec86c8b87e..5190a72d54 100644 --- a/components/aiprompt/toolbar.md +++ b/components/aiprompt/toolbar.md @@ -1,7 +1,7 @@ --- title: Toolbar page_title: AIPrompt - Toolbar -description: Configure and use the Blazor AIPrompt toolbar and its buttons. How to define custom toolbar buttons. +description: Learn how to configure and use the Blazor AIPrompt toolbar and its buttons, and see how to define custom toolbar buttons. slug: aiprompt-toolbar tags: telerik,blazor,aiprompt,ai,prompt,toolbar published: True @@ -10,12 +10,13 @@ position: 20 # AIPrompt ToolBar -The AIPrompt toolbar always renders buttons for the currently visible predefined views (Prompt, Output, and optionally, Command). These built-in buttons activate the appropriate view they represent. Any custom buttons will always appear after the view-related buttons. This article shows how to add custom tools to the AIPrompt's toolbar, which may invoke arbitrary commands or handlers. +The AIPrompt ToolBar renders buttons for the predefined views (Prompt, Output, and Command) and also allows you to add custom tools, which may invoke arbitrary commands or handlers. +The toolbar buttons for the Prompt and Output views are always available, while the one for the Commands view is optional. Any custom buttons that you add will always appear after the view-related buttons. ## Custom Tools -To define custom tools within the toolbar, use the `` tag, which is a standard Blazor `RenderFragment`. +To define custom tools within the ToolBar, use the `` tag, which is a standard Blazor `RenderFragment`. The example below omits any event handlers for brevity. Custom buttons are to be used for arbitrary logic which is not part of the AIPrompt component, thus feel free to attach the handlers you need. @@ -44,9 +45,9 @@ The example below omits any event handlers for brevity. Custom buttons are to be ## Next Steps -* [Customize the AIPrompt views]({%slug aiprompt-views-overview%}) -* [Implement AIPrompt templates]({%slug aiprompt-templates%}) -* [Handle AIPrompt events]({%slug aiprompt-events%}) +* [Customize the AIPrompt Views]({%slug aiprompt-views-overview%}) +* [Implement AIPrompt Templates]({%slug aiprompt-templates%}) +* [Handle AIPrompt Events]({%slug aiprompt-events%}) ## See Also diff --git a/components/aiprompt/views/commands.md b/components/aiprompt/views/commands.md index 392a7947b3..6d66c997e2 100644 --- a/components/aiprompt/views/commands.md +++ b/components/aiprompt/views/commands.md @@ -1,7 +1,7 @@ --- title: Commands View -page_title: AIPrompt Commands View -description: Explore the AIPrompt Commands View. Learn how to define custom commands. +page_title: AIPrompt - Commands View +description: Explore the AIPrompt's Commands view that displays a set of predefined commands and learn how to define your custom commands. slug: aiprompt-views-commands tags: telerik,blazor,aiprompt,ai,prompt,commands published: True @@ -22,12 +22,12 @@ The following properties enable you to customize each command: | Parameter | Type | Description | | ----------- | ----------- | ----------- | -| `Id` | `string` | The Id of the command. -| `Title` | `string` | The title of the command. Rendered as text within the Command View. | -| `Icon` | `object` | The [Telerik Font or SVG icon]({%slug common-features-icons%}) rendered before the title within the Command View. | -| `Children` | `List` | The nested commands(if any) of the command. | +| `Id` | `string` | The `Id` of the command. | +| `Title` | `string` | The title of the command. Rendered as text within the Command view. | +| `Icon` | `object` | The [Telerik Font or SVG icon]({%slug common-features-icons%}) rendered before the title within the Command view. | +| `Children` | `List` | The nested commands (if any) of the command. | ->caption Use the `Commands` parameter to pass a collection of predefined commands to the AIPrompt for Blazor +>caption Using the `Commands` parameter to pass a collection of predefined commands to the AIPrompt for Blazor ````CSHTML caption Use the `ButtonText` and `ButtonIcon` to alter the appearance of view button. diff --git a/components/aiprompt/views/overview.md b/components/aiprompt/views/overview.md index 601c58b48d..810a1424be 100644 --- a/components/aiprompt/views/overview.md +++ b/components/aiprompt/views/overview.md @@ -10,7 +10,7 @@ position: 0 # AIPrompt Views -The AIPrompt component provides three different predefined views. There is also the option to define custom views. Through interaction with the component, the user can change the currently active view. +The AIPrompt component provides three predefined views and also lets you create custom views. Through interaction with the component, the user can change the currently active view. The available built-in views are: @@ -20,7 +20,7 @@ The available built-in views are: ## Parameters ->caption The AIPrompt views provides various parameters that allow you to configure the component: +The AIPrompt views provide various parameters that allow you to configure the component: @[template](/_contentTemplates/common/parameters-table-styles.md#table-layout) @@ -28,27 +28,27 @@ The available built-in views are: | --- | --- | --- | | `ButtonText` | `string` | The text rendered within the toolbar button associated with the view. | | `ButtonIcon` | `object` | The [Telerik Font or SVG icon]({%slug common-features-icons%}) rendered within the toolbar button associated with the view. | -| `ViewTemplate` | `RenderFragment` | The ViewTemplate allows you to control the rendering of the content of the view. Read more in the [Templates]({%slug aiprompt-views-templates%}#viewtemplate) article. | -| `FooterTemplate` | `RenderFragment` | The FooterTemplate allows you to control the rendering of the footer of the view. Read more in the [Templates]({%slug aiprompt-views-templates%}#footertemplate) article. | +| `ViewTemplate` | `RenderFragment` | The template controlling the rendering of the view's content. Read more in the [Templates]({%slug aiprompt-views-templates%}#viewtemplate) article. | +| `FooterTemplate` | `RenderFragment` | The template controlling the rendering of the view's footer. Read more in the [Templates]({%slug aiprompt-views-templates%}#footertemplate) article. | ->caption By default, the AIPrompt will always render both the Prompt and the Output view. The Commands view will be rendered only if a custom set of commands has been passed through the `Commands` parameter. +By default, the AIPrompt will always render both the Prompt and the Output view. The Commands view will be rendered only if you pass a custom set of commands through the `Commands` parameter: ````CSHTML -@* The user can only navigate between the Prompt and Output views - the Commands view, for example, will not be rendered, as no commands has been passed to the `Commands` parameter. *@ +@* The user can only navigate between the Prompt and Output views - the Commands view, for example, will not be rendered, as no commands have been passed to the `Commands` parameter. *@ @code { private void HandlePromptRequest(AIPromptPromptRequestEventArgs args) { - // dummy data intentionally used. Replace the hard-coded string with a call to your AI API. + // The example uses dummy data intentionally. Replace the hard-coded string with a call to your AI API. args.Output = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."; } } ```` ->caption Use the `ButtonText` and `ButtonIcon` parameters to customize the appearance of the toolbar buttons associated with the predefined views. +>caption Using the `ButtonText` and `ButtonIcon` parameters to customize the appearance of the toolbar buttons ````CSHTML @@ -65,7 +65,7 @@ The available built-in views are: @code { private void HandlePromptRequest(AIPromptPromptRequestEventArgs args) { - // dummy data intentionally used. Replace the hard-coded string with a call to your AI API. + // The example uses dummy data intentionally. Replace the hard-coded string with a call to your AI API. 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."; } } diff --git a/components/aiprompt/views/prompt.md b/components/aiprompt/views/prompt.md index 2153571fd3..58c304c0a8 100644 --- a/components/aiprompt/views/prompt.md +++ b/components/aiprompt/views/prompt.md @@ -1,7 +1,7 @@ --- title: Prompt View -page_title: AIPrompt Prompt View -description: Explore the AIPrompt Prompt View. Learn how to pass a set of prompt suggestions. +page_title: AIPrompt - Prompt View +description: Explore the AIPrompt Prompt view that allows users to type their queries, and learn how to pass a set of prompt suggestions. slug: aiprompt-views-prompt tags: telerik,blazor,aiprompt,prompt published: True @@ -10,11 +10,11 @@ position: 10 # AIPrompt Prompt View -The Prompt View features the prompt input, where users can type their query. It also contains a button to trigger a response request. +The Prompt view features the prompt input, where users can type their query. It also contains a button to trigger a response request. -Additionally, the Prompt View can contain prompt suggestions related to the prompt itself through the `PromptSuggestions` parameter. The user can select any of the available suggestions, which in turn will populate the prompt input with the selected suggestion. This interaction will not trigger a response request right away - the user can modify the suggestion first. +Additionally, the Prompt view can display prompt suggestions related to the prompt itself. To control these suggestions, use the `PromptSuggestions` parameter. The user can select any of the available suggestions, which in turn will populate the prompt input with the selected suggestion. This interaction will not trigger a response request right away—the user can modify the suggestion first. ->caption Use the `PromptSuggestions` to display a set of predefined prompts or hints. +>caption Using `PromptSuggestions` to display a set of predefined prompts or hints. ````CSHTML @@ -29,7 +29,7 @@ Additionally, the Prompt View can contain prompt suggestions related to the prom private void HandlePromptRequest(AIPromptPromptRequestEventArgs args) { - // dummy data intentionally used. Replace the hard-coded string with a call to your AI API. + // The example uses dummy data intentionally. Replace the hard-coded string with a call to your AI API. args.Output = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."; } } diff --git a/components/aiprompt/views/templates.md b/components/aiprompt/views/templates.md index 96fdfa89b3..ca9a632908 100644 --- a/components/aiprompt/views/templates.md +++ b/components/aiprompt/views/templates.md @@ -1,7 +1,7 @@ --- title: Templates -page_title: AIPrompt Views Templates -description: View Templates in AIPrompt for Blazor. Learn how to customize the appearance of individual views. +page_title: AIPrompt - Views Templates +description: Explore the View Templates in the AIPrompt component for Blazor. Learn how to use them to customize the appearance of the individual views. slug: aiprompt-views-templates tags: telerik,blazor,aiprompt,ai,prompt,templates published: True @@ -10,18 +10,17 @@ position: 40 # AIPrompt Views Templates -This article explains the available templates for the Views of the AIPrompt for Blazor. +This article explains the available templates for the views of the AIPrompt for Blazor. -- [AIPrompt Views Templates](#aiprompt-views-templates) - - [ViewTemplate](#viewtemplate) - - [FooterTemplate](#footertemplate) +- [View Template](#viewtemplate) +- [Footer Template](#footertemplate) -## ViewTemplate +## View Template -The `ViewTemplate` allows you to control the rendering of view's content. You can define it for each of the predefined Views: +The `ViewTemplate` allows you to control the rendering of view's content. You can define it for each of the predefined views: ->caption Use the ViewTemplate to alter the appearance of the prompt view +>caption Using the `ViewTemplate` to alter the appearance of the Prompt view ````CSHTML @@ -43,11 +42,11 @@ The `ViewTemplate` allows you to control the rendering of view's content. You ca } ```` -## FooterTemplate +## Footer Template The `FooterTemplate` allows you to control the rendering of the footer within individual views. ->caption Use the FooterTemplate to define a custom button. +>caption Using the `FooterTemplate` to define a custom button. ````CSHTML @@ -69,7 +68,7 @@ The `FooterTemplate` allows you to control the rendering of the footer within in private void HandlePromptRequest() { - // dummy data intentionally used. Replace the hard-coded string with a call to your AI API. + // The example uses dummy data intentionally. Replace the hard-coded string with a call to your AI API. AIPromptRef.AddOutput( output: "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", title: "Generated response", From e39c99375c64642ad3284fccbbb36f07bdb28c69 Mon Sep 17 00:00:00 2001 From: radkostanev Date: Mon, 29 Jan 2024 17:10:28 +0200 Subject: [PATCH 5/5] docs(aiprompt): address latest changes --- components/aiprompt/events.md | 1 - components/aiprompt/overview.md | 2 +- components/aiprompt/toolbar.md | 55 +++++++++++++++++++++++--- components/aiprompt/views/templates.md | 4 +- 4 files changed, 52 insertions(+), 10 deletions(-) diff --git a/components/aiprompt/events.md b/components/aiprompt/events.md index eb60a1581f..57e2b0cc4e 100644 --- a/components/aiprompt/events.md +++ b/components/aiprompt/events.md @@ -44,7 +44,6 @@ The event handler receives an argument of type [`AIPromptCommandDescriptorExecut | Property | Type | Description | | --- | --- | --- | | `Command` | `AIPromptCommandDescriptor` | The executed command. | -| `ParentCommand` | `AIPromptCommandDescriptor` | The parent of the executed command. | | `Output` | `string` | The output based on the executed command. | | `IsCancelled` | `bool` | Whether the event is cancelled and the built-in action is prevented. | | `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). | diff --git a/components/aiprompt/overview.md b/components/aiprompt/overview.md index 97ba398527..cac998acd3 100644 --- a/components/aiprompt/overview.md +++ b/components/aiprompt/overview.md @@ -91,7 +91,7 @@ The table below lists the AIPrompt parameters. For a full list of the AIPrompt A | Parameter | Type and Default Value | Description | | --- | --- | --- | | `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. | -| `AIPromptToolBarItems` | `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. | +| `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. | | `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. | | `PromptTextChanged` | `EventCallback` | The handler called whenever the `PromptText` changes. | | `PromptSuggestions` | `List` | The prompt suggestions displayed within the Prompt view. | diff --git a/components/aiprompt/toolbar.md b/components/aiprompt/toolbar.md index 5190a72d54..250b3159ab 100644 --- a/components/aiprompt/toolbar.md +++ b/components/aiprompt/toolbar.md @@ -13,10 +13,38 @@ position: 20 The AIPrompt ToolBar renders buttons for the predefined views (Prompt, Output, and Command) and also allows you to add custom tools, which may invoke arbitrary commands or handlers. The toolbar buttons for the Prompt and Output views are always available, while the one for the Commands view is optional. Any custom buttons that you add will always appear after the view-related buttons. +* [Built-in Tools](#built-in-tools) +* [Custom Tools](#custom-tools) + + +## Built-in Tools + +### AIPromptToolBarButton + +The AI Prompt ToolBar button is a plain button that you can click and it raises an event so the application can respond to that. + +You can add multiple buttons to the Telerik AIPrompt. To do that you should add the `` to the ``. + +### AIPromptToolBarButton parameters + +The `AIPromptToolBarButton` tag exposes parameters that allow you to customize the buttons: + +@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout) + +| Parameter | Type and Default Value | Description | +| ----------- | ----------- | ----------- | +| `Class` | `string` | The CSS class that will be rendered on the main wrapping element of the AIPromptToolBarButton. You could use that class to cascade styles. | +| `Icon` | `object` | Adds a font icon to the button. You can find more information on adding a font icon to a Telerik Component in [Telerik Font and Svg Icons article]({%slug common-features-icons%}#icon-in-telerik-component). | +| `OnClick` | `EventCallback` | The onclick event handler. | +| `ChildContent` | `RenderFragment` | The child content rendered within the button. | + +### AIPromptToolBarSpacer + +The spacer consumes the available empty space and push the rest of the tools next to one another. ## Custom Tools -To define custom tools within the ToolBar, use the `` tag, which is a standard Blazor `RenderFragment`. +To define custom tools within the ToolBar, use the `` tag, which is a standard Blazor `RenderFragment`. The example below omits any event handlers for brevity. Custom buttons are to be used for arbitrary logic which is not part of the AIPrompt component, thus feel free to attach the handlers you need. @@ -24,9 +52,19 @@ The example below omits any event handlers for brevity. Custom buttons are to be ````CSHTML - - Custom Button - + + My Button + + + + Insert + + Insert above + Insert below + + + + @code { @@ -35,9 +73,14 @@ The example below omits any event handlers for brevity. Custom buttons are to be // handle the prompt request here. } - private void OnCustomButtonClick() + private void OnToolBarButtonClick() + { + // handle the toolbar button click here. + } + + private void OnSplitButtonClick() { - // handle the custom button click here. + // handle the split button click here. } } ```` diff --git a/components/aiprompt/views/templates.md b/components/aiprompt/views/templates.md index ca9a632908..a0af563104 100644 --- a/components/aiprompt/views/templates.md +++ b/components/aiprompt/views/templates.md @@ -12,8 +12,8 @@ position: 40 This article explains the available templates for the views of the AIPrompt for Blazor. -- [View Template](#viewtemplate) -- [Footer Template](#footertemplate) +- [View Template](#view-template) +- [Footer Template](#footer-template) ## View Template