diff --git a/_config.yml b/_config.yml index acd260768..3218750ac 100644 --- a/_config.yml +++ b/_config.yml @@ -427,6 +427,8 @@ navigation: title: "PivotGrid" "*/radiogroup": title: "RadioGroup" + "*rootcomponent": + title: "RootComponent" "*scheduler": title: "Scheduler" "*scrollview": diff --git a/_contentTemplates/common/get-started.md b/_contentTemplates/common/get-started.md index 57c5dc9c5..bf07c62e8 100644 --- a/_contentTemplates/common/get-started.md +++ b/_contentTemplates/common/get-started.md @@ -3,7 +3,7 @@ ## Prerequisites -* To successfully complete the steps in this tutorial, make sure that you have installed a current Visual Studio version. +* To successfully complete the steps in this tutorial, make sure you have an up-to-date Visual Studio, which is compatible with the .NET version of your choice. If you are not using Visual Studio, some of the steps require using the .NET CLI or editing files manually. In this case, also refer to the tutorial [Typical Workflow]({%slug getting-started/what-you-need%}). * To learn more about the compatibility of the Telerik UI for Blazor components with different browser and .NET versions, see the [system requirements]({%slug system-requirements%}). diff --git a/components/rootcomponent/overview.md b/components/rootcomponent/overview.md new file mode 100644 index 000000000..70dabf90d --- /dev/null +++ b/components/rootcomponent/overview.md @@ -0,0 +1,109 @@ +--- +title: Overview +page_title: RootComponent - Overview +description: Overview of the Telerik Root Component for Blazor. +slug: rootcomponent-overview +tags: telerik,blazor,telerikrootcomponent,rootcomponent +published: True +position: 0 +--- + +# TelerikRootComponent Overview + +The `TelerikRootComponent` is a special component in Telerik UI for Blazor. Its placement and configuration will affect all its child Telerik Blazor components. This article describes the purpose and usage of `TelerikRootComponent`. + + +## Purpose + +The `TelerikRootComponent` is responsible for the following tasks: + +* It provides settings to all its child Telerik components, for example about the [icon type]({%slug common-features-icons%}#set-global-icon-type) or [right-to-left (RTL) support]({%slug rtl-support%}). +* It renders all Telerik popups, which has the following benefits: + * It's more reliable that the popups will display on top of the other page content. + * There is no risk for the popups to be trapped by scrollable containers, or clipped by containers with an `overflow:hidden` style. +* It exposes the `DialogFactory` for using [predefined dialogs]({%slug dialog-predefined%}). + +The `TelerikRootComponent` achieves all these tasks with the help of [cascading values](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/cascading-values-and-parameters). That's why it is crucial for the root component to wrap all other Telerik components in the app. To ensure correct popup position, it is also highly recommended for the `TelerikRootComponent` to be the top-level component in the app and wrap all other content, including the application layout. + + +## Using TelerikRootComponent + +The recommended way to add `TelerikRootComponent` to a Blazor app is to: + +1. Create a new layout file in the app, for example, `TelerikLayout.razor`. +1. (optional) Place the new layout in the same folder as the default application layout (usually `MainLayout.razor`). +1. Add a `` tag to the new layout and set `@Body` as the root component's child content. +1. Make the new layout a parent of the default application layout. + +The above approach has the following benefits: + +* There is a separation of concerns and the `TelerikRootComponent` can be a parent of multiple other layouts. +* You can use `DialogFactory` (predefined Telerik dialogs) in `MainLayout.razor`. + +However, it is also possible to [add `` directly to the existing application layout(s)](#adding-telerikrootcomponent-to-existing-layout). + +>caption Adding TelerikRootComponent to a new layout + +
+ +````TelerikLayout.razor +@inherits LayoutComponentBase + + + @Body + +```` +````MainLayout.razor +@inherits LayoutComponentBase +@layout TelerikLayout + +@* The other MainLayout.razor content remains the same. *@ +```` + +### Adding TelerikRootComponent to Existing Layout + +>caption Adding TelerikRootComponent to MainLayout.razor + +
+ +````CSHTML +@inherits LayoutComponentBase + + + @* All the MainLayout.razor content becomes nested in the Telerik root component. *@ + +```` + + +## .NET 8 Notes + +.NET 8 introduced the concept of static Blazor apps with optional interactive components. The following requirements and considerations apply to the `TelerikRootComponent`: + +* The `TelerikRootComponent` must reside in an interactive layout or component. +* Application layouts are interactive only if the whole app is interactive. To achieve this, set *Interactivity location* of the app to *Global* during app creation. +* When the whole app is interactive and the `TelerikRootComponent` is in an (interactive) layout file, the component provides cascading values to all other Telerik components in the app. +* When the app is static and the `TelerikRootComponent` is in a (static) layout file, its cascading values cannot reach other Telerik components, because [cascading values cannot pass data across render mode boundaries](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/cascading-values-and-parameters?view=aspnetcore-8.0#cascading-valuesparameters-and-render-mode-boundaries). As a result, you need to add the `TelerikRootComponent` on each interactive page (component). Component interactivity is inherited. +* When the `TelerikRootComponent` is added to a `.razor` file, you cannot reference the `DialogFactory` and use [predefined dialogs]({%slug dialog-predefined%}) in the same `.razor` file (but a [workaround exists](https://github.com/telerik/blazor-ui/tree/master/rootcomponent/BlazorWebAppServer)). The `DialogFactory` will be available to child components of the `TelerikRootComponent`. See section [Using TelerikRootComponent](#using-telerikrootcomponent) above for more information and examples. + +See the following resources for more details and examples of using Telerik Blazor components and `TelerikRootComponent` in .NET 8 apps. + +* [Interactivity Considerations]({%slug getting-started/web-app%}#interactivity-considerations) +* [Adding `TelerikRootComponent` to Blazor Web App]({%slug getting-started/web-app%}#43-add-the-telerikrootcomponent) +* [.NET 8 Blazor Web App sample project on GitHub](https://github.com/telerik/blazor-ui/tree/master/rootcomponent/BlazorWebAppServer) + + +## TelerikRootComponent Parameters + +@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout) + +| Parameter | Type and Default Value | Description | +| --- | --- | --- | +| `EnableRtl` | `bool` | Enables [right-to-left (RTL) support]({%slug rtl-support%}). | +| `IconType` | `IconType` enum
(`Svg`) | The icon type, which other Telerik components will use to render internal icons. Regardless of this parameter value, you can use freely the [``]({%slug common-features-icons%}#fonticon-component) and [``]({%slug common-features-icons%}#svgicon-component) components, and [set the `Icon` parameter of other Telerik components]({%slug button-icons%}) to any type that you wish. | +| `Localizer` | `Telerik.Blazor.Services.ITelerikStringLocalizer` | The Telerik localization service. Normally, the [localizer should be defined as a service in `Program.cs`]({%slug globalization-localization%}). Use the `Localizer` parameter only in special cases when this is not possible. | + + +## See Also + +* [Popup Troubleshooting]({%slug troubleshooting-general-issues%}) +* [Setting up Telerik Blazor apps]({%slug getting-started/what-you-need%}) diff --git a/getting-started/client-blazor.md b/getting-started/client-blazor.md index ebeb95976..19faf92a6 100644 --- a/getting-started/client-blazor.md +++ b/getting-started/client-blazor.md @@ -10,7 +10,14 @@ position: 2 # First Steps with Client-Side UI for Blazor -This article explains how to get the Telerik UI for Blazor components in your **Client-side (WebAssembly)** Blazor project and start using them quickly. You will create a new application from scratch, learn how to add the UI for Blazor components to a project, and finally, add a UI component to a view. +This article explains how to get the Telerik UI for Blazor components in your Blazor WebAssembly app and start using them quickly. You will create a new application from scratch, learn how to add the UI for Blazor components to a project, and finally, add a UI component to a view. + +> This article applies only to the following Visual Studio project templates: +> +> * **Blazor WebAssembly App**, which exists up to .NET 7. +> * **Blazor WebAssembly Standalone App** for .NET 8. +> +> If you prefer the .NET 8 **Blazor Web App** template, then follow the [tutorial about .NET 8 Blazor Web App]({%slug getting-started/web-app%}). @[template](/_contentTemplates/common/get-started.md#prerequisites-download) diff --git a/getting-started/server-blazor.md b/getting-started/server-blazor.md index 3129e1e0a..06d8236eb 100644 --- a/getting-started/server-blazor.md +++ b/getting-started/server-blazor.md @@ -10,7 +10,9 @@ position: 3 # First Steps with Server-Side UI for Blazor -This article explains how to get the Telerik UI for Blazor components in your **Server-side** Blazor project and start using them quickly. You will create a new application from scratch, learn how to add the UI for Blazor components to a project, and finally, add a UI component to a view. +This article explains how to get the Telerik UI for Blazor components in your .NET 6 or 7 Blazor Server app and start using them quickly. You will create a new application from scratch, learn how to add the UI for Blazor components to a project, and finally, add a UI component to a view. + +> This article applies only to the **Blazor Server App** template in Visual Studio, which exists up to .NET 7. If you are using .NET 8, then follow the [tutorial about .NET 8 Blazor Web App]({%slug getting-started/web-app%}). @[template](/_contentTemplates/common/get-started.md#prerequisites-download) diff --git a/getting-started/web-app.md b/getting-started/web-app.md index 8c814ee8d..c50ce0187 100644 --- a/getting-started/web-app.md +++ b/getting-started/web-app.md @@ -10,7 +10,7 @@ position: 4 # First Steps with UI for Blazor in a Web App -This article explains how to use the Telerik UI for Blazor components into a .NET 8 Blazor Web App project template. You will create a new application from scratch, learn how to add the UI for Blazor components to a project, and finally, add a UI component to a view. +This article explains how to use the Telerik UI for Blazor components in a .NET 8 Blazor Web App project template. You will create a new application from scratch, learn how to add the UI for Blazor components to a project, and finally, add a UI component to a view. @[template](/_contentTemplates/common/get-started.md#prerequisites-download) @@ -20,10 +20,30 @@ This article explains how to use the Telerik UI for Blazor components into a .NET 8.0 introduces [new render modes for the Blazor components](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes?view=aspnetcore-8.0). At the time of writing, the default render mode is static and not interactive, so you need to make this change explicitly in your app. +> .NET 8.0 introduced [new render modes for the Blazor components](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes?view=aspnetcore-8.0). The default render mode is static and not interactive, so you need to make this change explicitly in your app. Make sure to review sections [Interactivity Considerations](#interactivity-considerations) and [`TelerikRootComponent` .NET 8 Notes]({%slug rootcomponent-overview%}#net-8-notes) if you are adding Telerik components to an existing .NET 8 Blazor web application. -How you add the `TelerikRootComponent` to the app depends on which of the following approaches for configuring the render mode you chose: +The `TelerikRootComponent` placement in the app depends on the selected *Interactivity location* during app creation: -* [Configure the Render Mode of the Entire App](#configure-the-render-mode-of-the-entire-app) -* [Configure the Render Mode per Page](#configure-the-render-mode-per-page) +* [Global](#431-apps-with-global-interactivity-location) +* [Per Page / Component](#432-apps-with-interactivity-location-set-to-per-page--component) +### 4.3.1 Apps with Global Interactivity Location -#### Configure the Render Mode of the Entire App - -You can set the render mode for the entire app as suggested in the [Blazor documentation](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes?view=aspnetcore-8.0#set-the-render-mode-for-the-entire-app). This will spare the need to set the render mode in every page and component. +You can set the render mode for the entire app as suggested in the [Blazor documentation](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes?view=aspnetcore-8.0#apply-a-render-mode-to-the-entire-app). This will spare the need to set the render mode in every page and component.
+ ````App.razor @@ -93,11 +113,11 @@ You can set the render mode for the entire app as suggested in the [Blazor docum @* ... *@ - + - + @* ... *@ @@ -122,7 +142,6 @@ You can set the render mode for the entire app as suggested in the [Blazor docum -
@@ -138,78 +157,57 @@ You can set the render mode for the entire app as suggested in the [Blazor docum ```` -#### Configure the Render Mode per Page - -As an alternative to setting the render mode for the entire app, you can set it only for specific pages and components. This is useful if you want to have different render modes in the app. In this case, make sure that the `TelerikRootComponent` is part of a component hierarchy that has interactive render mode. - -See the example below - the `TelerikRootComponent` must wrap all the content in the viewport, so the whole `
` is moved from the `MainLayout.razor` to the `TelerikLayout.razor`. +### 4.3.2 Apps with Interactivity Location set to Per Page / Component -
- -````MainLayout.razor -@inherits LayoutComponentBase - -@implements IDisposable - -@Body - -@code { - protected override Task OnInitializedAsync() - { - return base.OnInitializedAsync(); - } - - public void Dispose() - { - } -} -```` -````TelerikLayout.razor -@rendermode RenderMode.InteractiveServer +Instead of setting the interactive render mode for the entire app, you can also set it only for specific pages and components. This is useful if you want to have different render modes in the app. In this case, make sure that the `TelerikRootComponent` is part of a component hierarchy that is interactive. - +The Telerik components in `Home.razor` below are wrapped by a `TelerikContainer.razor` component, which includes the `TelerikRootComponent` and can be reused, so that the `TelerikRootComponent` is defined only once in the whole app. -
-
- -
+Also check this [.NET 8 Blazor Web App sample project on GitHub](https://github.com/telerik/blazor-ui/tree/master/rootcomponent/BlazorWebAppServer), which shows different ways to use the `TelerikRootComponent` and Telerik UI for Blazor in a static Blazor app. -
-
- About -
+
-
- @ChildContent -
-
-
+````TelerikContainer.razor +@* + The TelerikContainer allows you to use Telerik Blazor components in the interactive parts of a static app. + Place the TelerikContainer in interactive Razor components, which are children of static parents. -
- An unhandled error has occurred. - Reload - 🗙 -
+ The main purpose of the TelerikContainer component is to reuse a + TelerikRootComponent with the same settings. If you do not have any parameters for the TelerikRootComponent, + then you do not need a TelerikContainer. +*@ + + @ChildContent -@code{ +@code { [Parameter] - public RenderFragment ChildContent {get;set;} + public RenderFragment? ChildContent { get; set; } } ```` ````Home.razor @page "/" -@rendermode RenderMode.InteractiveServer +@rendermode InteractiveServer + + + @* must be recognized as a Razor component. + Depending on its location, you may need a @using statement in this file or in _Imports.razor. *@ + +

This part of the page is inside a TelerikRootComponent and can contain Telerik Blazor components.

- - @* must be recognized as a Razor component. *@ - @* You may need a @using statement in this file or in _Imports.razor. *@ +

+ Notice the usage of a TelerikContainer component. + Its main purpose is to reuse a TelerikRootComponent with the same settings. + If the TelerikRootComponent does not set any parameters, + then you do not need a TelerikContainer. +

@* Telerik UI for Blazor components here *@ - + ```` ### 4.4. Register the Telerik Blazor Service diff --git a/getting-started/what-you-need.md b/getting-started/what-you-need.md index f5451d71d..968008b2b 100644 --- a/getting-started/what-you-need.md +++ b/getting-started/what-you-need.md @@ -117,9 +117,9 @@ To use the Telerik components, you must add a few items to your projects. Some o 2. Follow the section for your project type: - * [Client-side (WASM)](#client-side-project-specifics) - * [Server-side](#server-side-project-specifics) - * [Web App Template](#web-app-template) + * [Client-side (WebAssembly)](#client-side-project-specifics) + * [Server-side (up to .NET 7)](#server-side-project-specifics) + * [Blazor Web App template](#web-app-template) * [Blazor Hybrid](#blazor-hybrid-project-specifics) diff --git a/introduction.md b/introduction.md index 49bf73bc4..840d5b76f 100644 --- a/introduction.md +++ b/introduction.md @@ -25,7 +25,7 @@ Visit the Telerik UI If you are new to Telerik UI for Blazor, visit the Getting Started tutorials that demonstrate how to add the Telerik components to your application: -* [Get Started with a Blazor Server app]({%slug getting-started/server-side%}) +* [Get Started with a .NET 6 or 7 Blazor Server app]({%slug getting-started/server-side%}) * [Get Started with a Blazor WebAssembly app]({%slug getting-started/client-side%}) * [Get Started with a .NET 8 Blazor Web App]({%slug getting-started/web-app%}) * [Get Started with Blazor Hybrid]({%slug getting-started/hybrid-blazor%})