Add TelerikRootComponent documentation

_config.yml

@@ -427,6 +427,8 @@ navigation:
  title: "PivotGrid"
  "*/radiogroup":
  title: "RadioGroup"
+ "*rootcomponent":
+ title: "RootComponent"
  "*scheduler":
  title: "Scheduler"
  "*scrollview":

components/rootcomponent/overview.md

@@ -0,0 +1,105 @@
+---
+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 `<TelerikRootComponent>` 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 `<TelerikRootComponent>` directly to the existing application layout(s)](#adding-telerikrootcomponent-to-existing-layout).
+
+>caption Adding TelerikRootComponent to a new layout
+
+<div class="skip-repl"></div>
+
+````TelerikLayout.razor
+@inherits LayoutComponentBase
+
+<TelerikRootComponent>
+ @Body
+</TelerikRootComponent>
+````
+````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
+
+<div class="skip-repl"></div>
+
+````CSHTML
+@inherits LayoutComponentBase
+
+<TelerikRootComponent>
+ @* All the MainLayout.razor content becomes nested in the Telerik root component. *@
+</TelerikRootComponent>
+````
+
+
+## .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. The factory will be available to child components of the `TelerikRootComponent`. See section [Using TelerikRootComponent](#using-telerikrootcomponent) above for more information and examples.
+
+Also see sections [Interactivity Considerations]({%slug getting-started/web-app%}#interactivity-considerations) and [Adding `TelerikRootComponent` to Blazor Web App]({%slug getting-started/web-app%}#43-add-the-telerikrootcomponent) for more details on using Telerik Blazor components and `TelerikRootComponent` in .NET 8 apps.
+
+
+## TelerikRootComponent Parameters
+
+@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
+
+| Parameter | Type and Default&nbsp;Value | Description |
+| --- | --- | --- |
+| `EnableRtl` | `bool` | Enables [right-to-left (RTL) support]({%slug rtl-support%}). |
+| `IconType` | `IconType` enum <br /> (`Svg`) | The icon type, which other Telerik components will use to render internal icons. Regardless of this parameter value, you can use freely the [`<TelerikFontIcon>`]({%slug common-features-icons%}#fonticon-component) and [`<TelerikSvgIcon>`]({%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%})

getting-started/web-app.md

@@ -31,7 +31,7 @@ Take into account the following notes when choosing the *Interactivity location*
 * We recommend *global* interactivity location for easier setup and usage of the Telerik components.
 * Most Telerik Blazor components require interactivity. They will not respond to user actions and the Blazor framework will not refresh their UI in static render mode. Telerik Blazor components with JavaScript rendering (Barcodes, Charts, Gauges, Maps, and QR Codes) will not render in static mode at all.
 * The `Account` section in the Blazor Web App template with identity is static by design. Most Telerik Blazor components will not work in this section.
-* The `TelerikRootComponent` requires interactivity as well. Normally, this component should be in a layout file. Layout files are interactive only if the *Interactivity location* is *Global*. If the *Interactivity location* is set to *Per page / component*, then there are three options:
+* The [`TelerikRootComponent` requires interactivity as well]({%slug rootcomponent-overview%}#net-8-notes). Normally, this component should be in a layout file. Layout files are interactive only if the *Interactivity location* is *Global*. If the *Interactivity location* is set to *Per page / component*, then there are three options:
  * Enable global interactivity at runtime when the user navigates to a page (component) with Telerik components inside. To do this, [set the `@rendermode` conditionally in `App.razor`](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes?view=aspnetcore-8.0#set-the-render-mode-by-component-instance). Blazor Web Apps with identity use the same approach to disable interactivity in the `Account` section.
  * Add a `TelerikRootComponent` on all interactive `.razor` pages, instead of using it in the layout component. A possible side effect may be [wrong popup position]({%slug troubleshooting-general-issues%}#wrong-popup-position).
  * Have a regular layout (`MainLayout.razor`) for static pages and one empty layout (`EmptyLayout.razor`) for interactive pages with Telerik components. Copy the contents for `MainLayout.razor` to a standard non-layout `.razor` file and use it to wrap the page-specific content. Replace `@Body` with `@ChildContent` in the copied layout content. This approach and code duplication require more effort to maintain, but avoids possible issues with popup position.
@@ -91,9 +91,9 @@ In the `~/_Imports.razor` file, add the `@using` directives below. This configur
 
 ### 4.3. Add the TelerikRootComponent
 
-Add a `TelerikRootComponent` component as a top-level component in the app and make sure it wraps all content. Normally, `TelerikRootComponent` is placed in a layout component, for example `MainLayout.razor` or a custom layout. `TelerikRootComponent` requires enabled [interactive mode](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes?view=aspnetcore-8.0), which is true for layout components only if the application's *Interactivity location* is *Global*.
+Add a `TelerikRootComponent` component as a top-level component in the app and make sure it wraps all content. Normally, `TelerikRootComponent` is placed in a layout component, for example `MainLayout.razor`. `TelerikRootComponent` requires enabled [interactive mode](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes?view=aspnetcore-8.0), which is true for layout components only if the application's *Interactivity location* is *Global*.
 
-> .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 section [Interactivity Considerations](#interactivity-considerations) above if you are adding Telerik components to an existing .NET 8 Blazor web application.
+> .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.
 
 The `TelerikRootComponent` placement in the app depends on the selected *Interactivity location* during app creation:
 
@@ -171,8 +171,8 @@ See the example below - the Telerik components in `Home.razor` are wrapped by a
  Place the TelerikContainer in interactive Razor components, which are children of static parents.
 
  The main purpose of the TelerikContainer component is to reuse a
- TelerikRootComponent with the same settings. If you don't have any parameters for the TelerikRootComponent,
- then you don't need a TelerikContainer.
+ TelerikRootComponent with the same settings. If you do not have any parameters for the TelerikRootComponent,
+ then you do not need a TelerikContainer.
 *@
 
 <TelerikRootComponent IconType="@IconType.Svg"
@@ -190,12 +190,6 @@ See the example below - the Telerik components in `Home.razor` are wrapped by a
 
 @rendermode InteractiveServer
 
-<p>
- This part of the page is not nested in a TelerikRootComponent.
- The Telerik Blazor components that do not use popups will work here,
- but this approach is not officially supported or recommended.
-</p>
-
 <TelerikContainer>
  @* <TelerikContainer> must be recognized as a Razor component.
  Depending on its location, you may need a @using statement in this file or in _Imports.razor. *@