Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

extend-application-shell

/extend-application-shell

Rozszerza powłokę i layout aplikacji ABP w MVC i Blazor hakami layoutu, globalnymi paskami narzędzi, nagłówkiem strony i brandingiem, bez kopiowania layoutu motywu.

Repozytorium
abp-skills ↗
Licencja
MIT
Ostatnia zmiana repozytorium
05.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
1
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 05.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co sprawdzić przed instalacją
  • SKILL.md zawiera komentarze HTML (1). Nie widać ich w podglądzie Markdown, a model je czyta.

Co robi i kiedy

Rozszerza powłokę i layout aplikacji ABP w MVC i Blazor hakami layoutu, globalnymi paskami narzędzi, nagłówkiem strony i brandingiem, bez kopiowania layoutu motywu.

Oryginalny opis (EN)

Extend the ABP application shell/layout across MVC and Blazor with layout hooks, global/page toolbars, the page header, and branding — without copying the theme layout. USE FOR: injecting content into the layout via AbpLayoutHookOptions + LayoutHooks (MVC ViewComponent hooks; Blazor Razor Component hooks + the App.razor LayoutHook component for the head); adding global toolbar items with StandardToolbars.Main + IToolbarContributor; setting page title/breadcrumb/toolbar via IPageLayout (MVC) or the PageHeader component (Blazor); customizing app name/logo with IBrandingProvider / DefaultBranding

Jak działa

  1. When to Use
  2. When Not to Use
  3. The core non-obvious rule: don't copy the layout
  4. Layout Hooks
  5. Toolbars: global vs page-level
  6. Page Header
  7. Branding
  8. Validation
  9. Common Pitfalls
Sekcje z nagłówków SKILL.md, w oryginale · 212 linii, 1 349 słów
Podgląd SKILL.md
---
name: extend-application-shell
description: >
  Extend the ABP application shell/layout across MVC and Blazor with layout hooks, global/page toolbars, the page header, and branding — without copying the theme layout.
  USE FOR: injecting content into the layout via AbpLayoutHookOptions + LayoutHooks (MVC ViewComponent hooks; Blazor Razor Component hooks + the App.razor LayoutHook component for the head); adding global toolbar items with StandardToolbars.Main + IToolbarContributor; setting page title/breadcrumb/toolbar via IPageLayout (MVC) or the PageHeader component (Blazor); customizing app name/logo with IBrandingProvider / DefaultBrandingProvider.
  DO NOT USE FOR: replacing or overriding a built-in module's own pages/components (use customize-application-modules); adding navigation menu items (use menus-and-localization); general MVC or Blazor page building (use mvc-razor-ui / blazor-ui); Angular shell customization (use angular-ui).
license: MIT
---

# Extend the ABP Application Shell

Guidance for extending the ABP **application shell** — the layout, toolbar, page header, and branding — across ASP.NET Core MVC / Razor Pages and Blazor. The point of this skill is that ABP ships the layout inside the **theme NuGet packages**, so the shell has documented extension points that are *not* derivable from plain ASP.NET Core or Blazor.

## When to Use

- Injecting content (analytics script, banner, `<head>` tags) into every page via layout hooks.
- Adding a global item (notification bell, custom control) to the shell's main toolbar.
- Setting a page's title, breadcrumb, or page-level toolbar.
- Changing the application name / logo shown in the shell.

## When Not to Use

- **Replacing a module's own page/component** — use the **customize-application-modules** skill.
- **Adding menu items** — use the **menus-and-localization** skill.
- **Building ordinary MVC or Blazor pages** — use **mvc-razor-ui** / **blazor-ui**.
- **Angular shell customization** — use the **angular-ui** skill.

## The core non-obvious rule: don't copy the layout

ABP's theming system places the page layout into the theme NuGet packages. The final application does **not** contain a `Layout.cshtml` (MVC) or `MainLayout.razor` (Blazor). You *can* copy the theme code into your solution and edit it freely — **but then you lose automatic theme updates** when you upgrade the theme package. The supported way to add content to the layout is the **Layout Hook System**, which lets you inject a component at defined hook points that every theme's layout implements.

## Layout Hooks

Register hooks in your module's `ConfigureServices` via `AbpLayoutHookOptions` and the `LayoutHooks` constants. **The component type differs by stack**:

- **MVC**: the hooked component is a **ViewComponent** (e.g. deriving from `AbpViewComponent`).
- **Blazor**: the hooked component is a **Razor Component**.

**MVC** — add a `ViewComponent` at the last position of the `<head>`:

```csharp
Configure<AbpLayoutHookOptions>(options =>
{
    options.Add(
        LayoutHooks.Head.Last,             // the hook point
        typeof(GoogleAnalyticsViewComponent) // the component to add
    );
});
```

**Blazor** — add a Razor Component at the end of the `<body>`:

```csharp
Configure<AbpLayoutHookOptions>(options =>
{
    options.Add(
        LayoutHooks.Body.Last,
        typeof(AnnouncementComponent)
    );
});
```

### Hook points

- MVC: `LayoutHooks.Head.First`, `LayoutHooks.Head.Last`, `LayoutHooks.Body.First`, `LayoutHooks.Body.Last`, **plus** `LayoutHooks.PageContent.First` and `LayoutHooks.PageContent.Last` (just before/after `@RenderBody()`).
- Blazor: `LayoutHooks.Head.First`, `LayoutHooks.Head.Last`, `LayoutHooks.Body.First`, `LayoutHooks.Body.Last` (no `PageContent.*`).

### Scoping to a layout

By default a hook is added to **all** layouts. Pass `layout:` to target one, using the `StandardLayouts` constants:

```csharp
options.Add(LayoutHooks.Head.Last, typeof(GoogleAnalyticsViewComponent),
    layout: StandardLayouts.Application);
```

MVC defines four standard layouts on `StandardLayouts`: `Application` (main/default — header, menu, footer, toolbar), `Account` (login/register pages under `/Pages/Account`), `Public` (public-facing pages), and `Empty`. Blazor defines `Application`, `Account`, `Public`, and `Empty`. If you don't specify a layout, the component renders in all layouts.

### Multiple contributors

You (or the modules you use) can add **multiple items to the same hook point**; all of them render in the order they were added. This is why hooks (not layout copies) are the right extension point — several modules can extend the shell at once without conflicting.

### Blazor `<head>` hooks need a `LayoutHook` in `App.razor`

Blazor's `App.razor` is the entry point. To make `LayoutHooks.Head.*` actually render, you must place the `<LayoutHook>` component manually inside the `<head>` of `App.razor`:

```razor
@using Volo.Abp.AspNetCore.Components.Web.Theming.Components.LayoutHooks;
@using Volo.Abp.Ui.LayoutHooks;
@using Volo.Abp.AspNetCore.Components.Web.Theming.Layout;

<head>
    <LayoutHook Name="@LayoutHooks.Head.First" Layout="@StandardLayouts.Application" />
    <!-- your head content -->
    <LayoutHook Name="@LayoutHooks.Head.Last" Layout="@StandardLayouts.Application" />
</head>
```

After registering these, the components you added to those hook points render in place. (Body hooks work without this step.)

## Toolbars: global vs page-level

These are **two different mechanisms** — don't confuse them.

### Global toolbar (`StandardToolbars.Main`)

There is one standard toolbar named "Main", the `StandardToolbars.Main` constant. Modules and your app add items to it, and the theme renders it on the layout. To contribute an item globally, implement `IToolbarContributor`. As with hooks, the item is a **ViewComponent** in MVC and a **Razor Component** in Blazor:

```csharp
public class MyToolbarContributor : IToolbarContributor
{
    public Task ConfigureToolbarAsync(IToolbarConfigurationContext context)
    {
        if (context.Toolbar.Name == StandardToolbars.Main)
        {
            context.Toolbar.Items.Insert(0, new ToolbarItem(typeof(NotificationViewComponent)));
        }
        return Task.CompletedTask;
    }
}
```

Register the contributor via `AbpToolbarOptions`:

```csharp
Configure<AbpToolbarOptions>(options =>
{
    options.Contributors.Add(new MyToolbarContributor());
});
```

Gate items by permission with `context.IsGrantedAsync("MyPermissionName")`, or the `RequirePermissions("MyPermissionName")` extension on a `ToolbarItem` (more performant — ABP batches the checks). `IToolbarManager` returns items by toolbar name and is used by themes to render the toolbar; you rarely call it directly.

> A theme may define its own desktop/mobile toolbar constants (e.g. the LeptonX Lite theme's `LeptonXLiteToolbars.Main` / `LeptonXLiteToolbars.MainMobile`). Check `context.Toolbar.Name` against the one your theme uses.

### Page-level toolbar (Blazor only, via `PageHeader`)

A page's own toolbar is unrelated to the global Main toolbar. In Blazor, set it on the `PageHeader` component with a `PageToolbar` and its `AddButton` extension (see Page Header below).

## Page Header

### MVC — `IPageLayout`

Inject `IPageLayout` into any page/view to set header properties; the theme renders them:

```csharp
@inject IPageLayout PageLayout
@{
    PageLayout.Content.Title = "Book List";
    PageLayout.Content.BreadCrumb.Add("Language Management");
    PageLayout.Content.MenuItemName = "BookStore.Books";
}
```

- `Content.Title` also feeds the HTML `<title>` (alongside the brand name).
- `Content.BreadCrumb.Add(text, url?, icon?)`; toggle `BreadCrumb.ShowHome` / `BreadCrumb.ShowCurrent`.
- `Content.MenuItemName` must match a menu item name from the navigation system so the theme marks it active.

### Blazor — `PageHeader` component

Add the `PageHeader` component to a page and drive it with parameters. The namespace differs by UI library: `Volo.Abp.AspNetCore.Components.Web.Theming.Layout` (Blazorise) or `Volo.Abp.AspNetCore.Components.Web.Theming.MudBlazor.Layout` (MudBlazor).

```razor
<PageHeader Title="Book List"
            BreadcrumbItems="@BreadcrumbItems"
            Toolbar="@Toolbar" />
```

```csharp
protected List<BreadcrumbItem> BreadcrumbItems { get; } = new();
protected PageToolbar Toolbar { get; } = new();

protected override void OnInitialized()
{
    BreadcrumbItems.Add(new BreadcrumbItem("Language Management"));
    Toolbar.AddButton("New Item", () => Task.CompletedTask, icon: /* IconName.Add or MudBlazor.Icons.Material.Filled.Add */);
}
```

- The breadcrumb item type is `Volo.Abp.BlazoriseUI.BreadcrumbItem` (Blazorise) or `MudBlazor.BreadcrumbItem` (MudBlazor) — they are different types with different constructors.
- Toggle `BreadcrumbShowHome` / `BreadcrumbShowCurrent` parameters.
- Globally enable/disable sections with `PageHeaderOptions` (`RenderPageTitle`, `RenderBreadcrumbs`, `RenderToolbar` — all `true` by default).

> The Basic theme doesn't render breadcrumbs or (MVC) the selected menu item; LeptonX / LeptonX Lite do.

## Branding

Both stacks use `IBrandingProvider` (namespace `Volo.Abp.Ui.Branding`) for the app name and logo. Implement the interface or inherit `DefaultBrandingProvider`, and register it as a replacement service:

```csharp
[Dependency(ReplaceServices = true)]
public class MyProjectBrandingProvider : DefaultBrandingProvider
{
    public override string AppName => "Book Store";
    public override string? LogoUrl => "/logo.png";
    public override string? LogoReverseUrl => "/logo-reverse.png";
}
```

`IBrandingProvider` exposes `AppName`, `LogoUrl`, and `LogoReverseUrl` (logo for a reverse/dark theme). It's evaluated on every page refresh, so a multi-tenant app can return a tenant-specific name/logo.

## Validation

- The web/Blazor host builds and runs; the injected content appears on the layout at the chosen hook point across pages.
- A layout hook targeting `LayoutHooks.Body.*` renders without extra wiring; a `LayoutHooks.Head.*` hook in Blazor renders **only** after a matching `<LayoutHook>` is present in `App.razor`.
- A `StandardToolbars.Main` contributor's item shows in the shell toolbar; permission-gated items appear only when the permission is granted.
- `IPageLayout` (MVC) / `PageHeader` (Blazor) update the title/breadcrumb — verify against a theme that renders them (LeptonX), since the Basic theme skips breadcrumbs.
- The `IBrandingProvider` override changes the app name/logo shown in the shell after replacing the service.

## Common Pitfalls

- **Copying the theme layout to customize it** — you lose theme package upgrades. Use `AbpLayoutHookOptions` + `LayoutHooks` instead.
- **Blazor `<head>` hook does nothing** — you registered a `LayoutHooks.Head.*` component but didn't add the `<LayoutHook Name="..." Layout="..." />` to `App.razor`'s `<head>`.
- **Confusing the two toolbar mechanisms** — `StandardToolbars.Main` + `IToolbarContributor` is the *global shell* toolbar; a page's own buttons go on the Blazor `PageHeader`'s `PageToolbar`. They are unrelated.
- **Wrong component kind for a hook/toolbar item** — MVC hooks and toolbar items are **ViewComponents**; Blazor ones are **Razor Components**. They are not interchangeable.
- **Assuming `PageContent.*` hooks exist in Blazor** — those hook points are MVC-only; Blazor has `Head.*` and `Body.*` only.
- **Expecting breadcrumbs/selected-menu on the Basic theme** — those are rendered by LeptonX / LeptonX Lite, not the Basic theme.
- **Mixing Blazorise and MudBlazor breadcrumb types** — `Volo.Abp.BlazoriseUI.BreadcrumbItem` and `MudBlazor.BreadcrumbItem` are distinct; use the one matching the project's UI library and `PageHeader` namespace.
- **Forgetting `[Dependency(ReplaceServices = true)]`** on the branding provider — without it, `DefaultBrandingProvider` stays in effect.

Wersje

W bazie nie ma innych skilli o nazwie extend-application-shell.

Migawka bazy z 13.11.2026 · wersja paczki 054a31640628 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 90blazor
    Podpowiada wzorce budowy komponentów i aplikacji w Blazorze dla plików .razor i .razor.cs.
  • 100abp-ui
    Opisuje warstwę UI w ABP Framework 10.x: MVC i Razor Pages, Blazor, Angular, React, theming LeptonX, menu contributor i dynamiczne proxy.
  • 100abp-ui
    Opisuje warstwę UI w ABP Framework 10.x: MVC i Razor Pages, Blazor, Angular, React, theming LeptonX, menu contributor i dynamiczne proxy.
  • 100secure-web-requests
    Konfiguruje ochronę CSRF i nagłówki bezpieczeństwa w ABP ASP.NET Core: ciasteczka antyforgery, CSP i nonce skryptów.
  • 100build-mvc-widgets
    Buduje wielokrotnego użytku widgety ABP MVC i Razor Pages: ViewComponent z atrybutem Widget, własnymi skryptami, stylami i bundle contributors oraz odświeżaniem po stronie serwera i klienta przez abp.WidgetManager.
  • 100convert-blazor-server-to-webapp
    Prowadzi migrację aplikacji Blazor Server sprzed .NET 8 do Blazor Web App na .NET 8+: AddRazorComponents, MapRazorComponents, App.razor zamiast _Host.cshtml i blazor.web.js.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.