diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000000..eb5cfec430 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,552 @@ +# Blazor Code Style Guide + +This guide outlines best practices for Razor component development and documentation in Blazor. + +## Razor File Structure + +Use the following top-down order in `.razor` files: + +1. `@page` +2. `@using` +3. `@namespace` +4. `@inherits` +5. `@implements` +6. `@inject` + +Insert ` #end + +#license-key-version + +>tip This documentation section applies to Telerik UI for Blazor version **8.0.0** and above. Older versions do not require a license key. + +#end + +#license-key-update-whenever + +>tip Update your license key [whenever you renew or purchase a new Telerik license](slug:installation-license-key#license-key-updates). + +#end + +#license-key-manual-steps + +To download and install your Telerik license key: + +1. Go to the License Keys page in your Telerik account. +1. Click the **Download License Key** button. +1. Save the `telerik-license.txt` file to: + * (on Windows) `%AppData%\Telerik\telerik-license.txt`, for example, `C:\Users\...\AppData\Roaming\Telerik\telerik-license.txt` + * (on Mac or Linux) `~/.telerik/telerik-license.txt`, for example, `/Users/.../.telerik/telerik-license.txt` + +This will make the license key available to all Telerik .NET apps that you develop on your local machine. + +#end + +#license-key-know-more-link + +The [Telerik License Key](slug:installation-license-key) article provides additional details on installing and updating your Telerik license key in different scenarios. [Automatic license key maintenance](slug:installation-license-key#automatic-installation) is more effective and recommended in the long run. + +#end + +#ai-coding-assistant-ad + +Use the [Telerik AI Coding Assistant](slug:ai-overview) through the [Telerik Blazor MCP server](slug:ai-mcp-server) or the [Telerik Blazor GitHub Copilot extension](slug:ai-copilot-extension). These tools help you receive tips and generate code snippets that include Telerik UI for Blazor components and API. + +#end \ No newline at end of file diff --git a/_contentTemplates/common/grid-treelist-autogenerated-columns.md b/_contentTemplates/common/grid-treelist-autogenerated-columns.md index 7e6ea30f96..f7dbfca1d4 100644 --- a/_contentTemplates/common/grid-treelist-autogenerated-columns.md +++ b/_contentTemplates/common/grid-treelist-autogenerated-columns.md @@ -1,4 +1,4 @@ #grid-treelist-autogenerated-columns-limitation When the component initializes, it expects to know what columns to render before the data comes. -If the component is bound to a collection of dynamic objects (such as `Dictionary` or `ExpandoObject`), the component cannot know what columns to render, due to the nature of these objects. Therefore, the `AutoGenerateColumns` feature is not applicable in such scenarios. Columns must be declared explicitly or with a loop. Examples of such setups are available at [Binding Grid to ExpandoObject]({%slug grid-kb-binding-to-expando-object%}). +If the component is bound to a collection of dynamic objects (such as `Dictionary` or `ExpandoObject`), the component cannot know what columns to render, due to the nature of these objects. Therefore, the `AutoGenerateColumns` feature is not applicable in such scenarios. Columns must be declared explicitly or with a loop. Examples of such setups are available at [Binding Grid to ExpandoObject](slug:grid-kb-binding-to-expando-object). #end \ No newline at end of file diff --git a/_contentTemplates/common/grid-treelist-editing-notes.md b/_contentTemplates/common/grid-treelist-editing-notes.md deleted file mode 100644 index ebc72c5096..0000000000 --- a/_contentTemplates/common/grid-treelist-editing-notes.md +++ /dev/null @@ -1,10 +0,0 @@ -#grid-treelist-data-operations-while-editing - - * For operations like Filter, Group, Sort, Page, Search, Select, Row drag and Delete: - * InCell edit - if the validation is satisfied, a save operation will be executed. If the validation is **not** satisfied, editing will be cancelled, the `OnCancel` event will fire and the new user operation will be executed. In this case, you can handle the OnCancel event and set the `IsCancelled` property of the `CommandEventArgs` to true. Thus, the other data operation will be aborted and the Grid will remain in edit mode. - * Inline edit - regardless of the validation, editing will be cancelled, the `OnCancel` event will fire and the new user operation will be executed. In this case, you can handle the OnCancel event and set the `IsCancelled` property of the `CommandEventArgs` to true. Thus, the other data operation will be aborted and the Grid will remain in edit mode. - - * For operations like Edit, Add, Save: - * InCell edit - if the validation is satisfied, the currently edited item will be saved and the command will be executed. If the validation is **not** satisfied, the command will be blocked until the item is valid or editing is cancelled. - * Inline edit - if the validation is satisfied, `OnCancel` will be fired for the currently edited item and the command will be executed. If the validation is **not** satisfied, the command will be blocked until the item is valid or editing is cancelled. -#end \ No newline at end of file diff --git a/_contentTemplates/common/icons.md b/_contentTemplates/common/icons.md index 74137ba8d8..dfc0c08ed0 100644 --- a/_contentTemplates/common/icons.md +++ b/_contentTemplates/common/icons.md @@ -1,6 +1,6 @@ #font-icons-css-note -> Make sure to [register `font-icons.css` if using Telerik font icons]({%slug common-features-icons%}#font-icon-stylesheet). +> Make sure to [register `font-icons.css` if using Telerik font icons](slug:common-features-icons#font-icon-stylesheet). #end diff --git a/_contentTemplates/common/inputs.md b/_contentTemplates/common/inputs.md index dd3418ff46..23374062b6 100644 --- a/_contentTemplates/common/inputs.md +++ b/_contentTemplates/common/inputs.md @@ -1,25 +1,23 @@ #focus-kb -Also check the dedicated KB article about [programmatic input component focusing]({%slug inputs-kb-focus%}), which provides more examples and tips. +Also check the dedicated KB article about [programmatic input component focusing](slug:inputs-kb-focus), which provides more examples and tips. #end #edit-debouncedelay - Consider setting `DebounceDelay="0"` to the component inside the editor template. This is how the default editors in all Telerik Blazor components work. Otherwise, fast users may try to save changes before the data item in edit mode receives the new value. - #end #adornments ## Adornments -The component allows you to add custom elements as prefixes and suffixes. [Read more about how to render custom adornments before and after the input element...]({%slug common-features/input-adornments%}) +The component allows you to add custom elements as prefixes and suffixes. [Read more about how to render custom adornments before and after the input element...](slug:common-features/input-adornments) #end - + #floating-label-and-preffix -When using the [`PrefixTemplate`]({%slug common-features/input-adornments%}#adding-prefix-in-ui-for-blazor-components) for a component wrapped in a [FloatingLabel]({%slug floatinglabel-overview%}), the label will overlap the prefix. +When using the [`PrefixTemplate`](slug:common-features/input-adornments#adding-a-prefix-adornment) for a component wrapped in a [FloatingLabel](slug:floatinglabel-overview), the label will overlap the prefix. To ensure both the FloatingLabel and the prefix content are properly displayed, move the label with CSS: -````CSHTML +````RAZOR -#end \ No newline at end of file +#end + +#multidimensional-table + +#end diff --git a/_contentTemplates/common/popup-edit-customization.md b/_contentTemplates/common/popup-edit-customization.md index 2def29e38a..08c6a8b4dd 100644 --- a/_contentTemplates/common/popup-edit-customization.md +++ b/_contentTemplates/common/popup-edit-customization.md @@ -6,7 +6,7 @@ | --- | --- | --- | | `Class` | `string` | The CSS class of the edit popup | | `Title` | `string` | The title of the edit popup | -| `ThemeColor` | `string` | The color scheme of the window. Use the available members of the static class [`ThemeConstants.Window.ThemeColor`](/blazor-ui/api/Telerik.Blazor.ThemeConstants.Window.ThemeColor). | +| `ThemeColor` | `string` | The color scheme of the window. Use the available members of the static class [`ThemeConstants.Window.ThemeColor`](slug:Telerik.Blazor.ThemeConstants.Window.ThemeColor). | | `Width` | `string` | The Width of the edit popup | | `MaxWidth` | `string` | The maximum width of the window | | `MinWidth` | `string` | The minimum width of the window | diff --git a/_contentTemplates/common/rebind-method.md b/_contentTemplates/common/rebind-method.md index e92896381e..50f5922aa7 100644 --- a/_contentTemplates/common/rebind-method.md +++ b/_contentTemplates/common/rebind-method.md @@ -1,5 +1,5 @@ #intro -You can refresh the data by invoking the [`Rebind` method]({%slug common-features-data-binding-overview%}#refresh-data). Use the component reference to call the `Rebind` method after you have made the data changes (for example adding, removing items). This is needed in case you are not using [Observable data](#observable-data) or [resetting the collection reference](#new-collection-reference). Calling `Rebind` will force the component process the available data anew to reflect the updates. +You can refresh the data by invoking the [`Rebind` method](slug:common-features-data-binding-overview#refresh-data). Use the component reference to call the `Rebind` method after you have made the data changes (for example adding, removing items). This is needed in case you are not using [Observable data](#observable-data) or [resetting the collection reference](#new-collection-reference). Calling `Rebind` will force the component process the available data anew to reflect the updates. >caption Use the `Rebind` method to refresh the data. #end \ No newline at end of file diff --git a/_contentTemplates/common/refresh-data-not-applicable.md b/_contentTemplates/common/refresh-data-not-applicable.md index 16e99bc0ea..6ff1f6996a 100644 --- a/_contentTemplates/common/refresh-data-not-applicable.md +++ b/_contentTemplates/common/refresh-data-not-applicable.md @@ -1,3 +1,3 @@ #refresh-data-note ->note As part of our `3.0.1` release we introduced the `Rebind` method to the component reference. This would make the rest of the approaches in this article obsolete. -#end \ No newline at end of file +>note As part of our `3.0.1` release we introduced the `Rebind` method to the component reference. This can make some of the approaches in this article obsolete, especially resetting the collection reference. +#end diff --git a/_contentTemplates/date-inputs/general.md b/_contentTemplates/date-inputs/general.md index d11374c765..96de7ceb92 100644 --- a/_contentTemplates/date-inputs/general.md +++ b/_contentTemplates/date-inputs/general.md @@ -26,19 +26,19 @@ By default, the value for all parameters is `null`, which applies the full forma #end #dateinput-typing-settings -textbox is a [DateInput component]({%slug components/dateinput/overview%}), which provides various parameters to configure the keyboard typing experience. The settings are related to: +textbox is a [DateInput component](slug:components/dateinput/overview), which provides various parameters to configure the keyboard typing experience. The settings are related to: * Caret placement; * Two-digit year values; * Automatic correction of invalid date segments. -See the [DateInput keyboard documentation]({%slug dateinput-keyboard-typing%}) for details and examples. The same DateInput parameters with the same behavior exist for the +See the [DateInput keyboard documentation](slug:dateinput-keyboard-typing) for details and examples. The same DateInput parameters with the same behavior exist for the #end #typing-parameters ### Typing User Experience -The component provides multiple parameters, which control the [caret placement, two-digit year values and the auto-correct behavior of the textbox. See the **DateInput** documentation for details]({%slug dateinput-keyboard-typing%}). +The component provides multiple parameters, which control the [caret placement, two-digit year values and the auto-correct behavior of the textbox. See the **DateInput** documentation for details](slug:dateinput-keyboard-typing). #end diff --git a/_contentTemplates/dropdownbutton/notes.md b/_contentTemplates/dropdownbutton/notes.md index 5f8c5becb4..18f06ac0ba 100644 --- a/_contentTemplates/dropdownbutton/notes.md +++ b/_contentTemplates/dropdownbutton/notes.md @@ -1,7 +1,7 @@ #dropdownbutton-splitbutton-comparison The DropDownButton and SplitButton components are similar. They both consist of a primary button and a dropdown element that holds additional action items. The major difference is the purpose of the primary button. -* [DropDownButton]({%slug dropdownbutton-overview%})—The main purpose of the primary button is to open the popup with additional actions. The primary button exposes a separate [`OnClick` event]({%slug dropdownbutton-events%}), which can invoke a dedicated action. Clicking on the DropDownButton always opens the dropdown. +* [DropDownButton](slug:dropdownbutton-overview)—The main purpose of the primary button is to open the popup with additional actions. The primary button exposes a separate [`OnClick` event](slug:dropdownbutton-events), which can invoke a dedicated action. Clicking on the DropDownButton always opens the dropdown. -* [SplitButton]({%slug splitbutton-overview%})—The main element contains a primary button and a separate button for opening the dropdown. The purpose of the primary button is to [invoke a standalone action]({%slug splitbutton-events%}#onclick). Clicking on it does not open the dropdown. To open the popup with the additional actions, the user has to click the dedicated button with `caret-alt-down` icon. It is possible to [switch the primary and dropdown actions programmatically]({%slug splitbutton-kb-change-primary-action-onclick%}). +* [SplitButton](slug:splitbutton-overview)—The main element contains a primary button and a separate button for opening the dropdown. The purpose of the primary button is to [invoke a standalone action](slug:splitbutton-events#onclick). Clicking on it does not open the dropdown. To open the popup with the additional actions, the user has to click the dedicated button with `caret-alt-down` icon. It is possible to [switch the primary and dropdown actions programmatically](slug:splitbutton-kb-change-primary-action-onclick). #end \ No newline at end of file diff --git a/_contentTemplates/dropdowns/adaptive-rendering.md b/_contentTemplates/dropdowns/adaptive-rendering.md index 7d81bba92f..7930387cdb 100644 --- a/_contentTemplates/dropdowns/adaptive-rendering.md +++ b/_contentTemplates/dropdowns/adaptive-rendering.md @@ -1,7 +1,7 @@ #intro -The component supports different popup rendering depending on the screen size. [Read more about the Adaptive Rendering functionality and how to enable it...]({%slug adaptive-rendering%}) +The component supports different popup rendering depending on the screen size. [Read more about the Adaptive Rendering functionality and how to enable it...](slug:adaptive-rendering) #end #value-changed -> If [`AdaptiveRendering`]({%slug adaptive-rendering%}) is enabled, on small and medium devices `ValueChanged` will fire only when the user clicks the confirmation button in the action sheet. +> If [`AdaptiveRendering`](slug:adaptive-rendering) is enabled, on small and medium devices `ValueChanged` will fire only when the user clicks the confirmation button in the action sheet. #end \ No newline at end of file diff --git a/_contentTemplates/dropdowns/features.md b/_contentTemplates/dropdowns/features.md index bdb0e6634a..f8a23bb91a 100644 --- a/_contentTemplates/dropdowns/features.md +++ b/_contentTemplates/dropdowns/features.md @@ -15,7 +15,7 @@ You can use the functionality of the built-in templates and customize the defaul #end #validation -You can ensure that the component value is acceptable by using the built-in validation. [Read more about input validation...]({%slug common-features/input-validation%}). +You can ensure that the component value is acceptable by using the built-in validation. [Read more about input validation...](slug:common-features/input-validation). #end #virtualization @@ -25,7 +25,7 @@ By virtualizing the elements in the dropdown, you can use huge data sources with #styling | Parameter | Type | Description | | --- | --- | --- | -| `Class` | `string` | The CSS class that will be rendered on the main wrapping element of the component. Use it to [override the theme or apply custom styles]({%slug themes-override%}). | +| `Class` | `string` | The CSS class that will be rendered on the main wrapping element of the component. Use it to [override the theme or apply custom styles](slug:themes-override). | | `Width` | `string` | The width of the component. It will target both the dropdown and the main element if the dropdown has no specific width set. @[template](/_contentTemplates/inputs/inputs-width-template.md#inputs-width-information) | #end @@ -43,7 +43,7 @@ By virtualizing the elements in the dropdown, you can use huge data sources with | `MaxWidth` | `string` | The maximum width of the popup. | | `Width` | `string` | The width of the popup. If you don't specify a value, the dropdown width will match the anchor element width which can help with responsive layouts and 100% widths. | -The parameters that modify the popup dimensions (`Height`, `Width`, `MaxWidth`, etc.) expect [valid CSS values]({%slug common-features/dimensions%}). +The parameters that modify the popup dimensions (`Height`, `Width`, `MaxWidth`, etc.) expect [valid CSS values](slug:common-features/dimensions). The `MinHeight` and `MaxHeight` have no effect if the `Height` is always within their range. The min and max values are useful only when the dropdown height is set to a relative unit or changes at runtime. diff --git a/_contentTemplates/editor/general.md b/_contentTemplates/editor/general.md index c464d4da0e..53201c6172 100644 --- a/_contentTemplates/editor/general.md +++ b/_contentTemplates/editor/general.md @@ -8,7 +8,7 @@ The application must sanitize the content before passing it to the Editor and, o This section applies only to Blazor **Server** apps. Blazor **WebAssembly** apps do not require additional configuration for the Editor to work with large content. -Blazor **Server** apps use the **SignalR WebSocket** to send the Editor `Value` from the browser to the server .NET runtime and vice-versa. The default SignalR maximum message size is **32 KB**. To work with larger content (especially paste images as Base64 strings), [increase the max WebSocket message size for the Blazor application]({%slug common-kb-increase-signalr-max-message-size%}). +Blazor **Server** apps use the **SignalR WebSocket** to send the Editor `Value` from the browser to the server .NET runtime and vice-versa. The default SignalR maximum message size is **32 KB**. To work with larger content (especially paste images as Base64 strings), [increase the max WebSocket message size for the Blazor application](slug:common-kb-increase-signalr-max-message-size). #end #prosemirror-schema-prerequisites diff --git a/_contentTemplates/grid/built-in-dialogs.md b/_contentTemplates/grid/built-in-dialogs.md index 0597d3b8bc..90db720dd0 100644 --- a/_contentTemplates/grid/built-in-dialogs.md +++ b/_contentTemplates/grid/built-in-dialogs.md @@ -1,11 +1,11 @@ #delete-confirmation To customize the appearance and behavior of the delete confirmation dialog, use one of the following options: -* [Localization]({%slug globalization-localization%}) - this approach is useful if you want to change just the text of the built-in delete confirmation dialog elements. It does not allow adding item details to the dialog text. +* [Localization](slug:globalization-localization) - this approach is useful if you want to change just the text of the built-in delete confirmation dialog elements. It does not allow adding item details to the dialog text. -* [Predefined dialogs (`DialogFactory`)]({%slug dialog-predefined%}#confirm) - this option is useful if you want to change the dialog text and include some details for the item the user tries to delete (for example, record name). +* [Predefined dialogs (`DialogFactory`)](slug:dialog-predefined#confirm) - this option is useful if you want to change the dialog text and include some details for the item the user tries to delete (for example, record name). -* [Dialog Component]({%slug dialog-overview%}) - this solution allows you to fully customize the rendering and appearance of the dialog. You may set the desired `ThemeColor` and add any content there, be that custom text, HTML elements or other components. +* [Dialog Component](slug:dialog-overview) - this solution allows you to fully customize the rendering and appearance of the dialog. You may set the desired `ThemeColor` and add any content there, be that custom text, HTML elements or other components. -[Read more about customizing the delete confirmation dialog...]({%slug grid-kb-customize-delete-confirmation-dialog%}) +[Read more about customizing the delete confirmation dialog...](slug:grid-kb-customize-delete-confirmation-dialog) #end \ No newline at end of file diff --git a/_contentTemplates/grid/common-link.md b/_contentTemplates/grid/common-link.md index f97abbd559..b98b81d664 100644 --- a/_contentTemplates/grid/common-link.md +++ b/_contentTemplates/grid/common-link.md @@ -4,7 +4,7 @@ #conditional-style-row-and-cell-render -````CSHTML +````RAZOR @* Conditional styling/formatting for a cell and row *@ + +
ChartCategoryAxis
ChartCategoryAxis