Orchardcore Breadcrumbs

OrchardCore Breadcrumbs

A breadcrumb is a named trail with an explicit current-page title. The parent <breadcrumb> requires an IHtmlContent title and normalizes it to text; every <breadcrumb-item> child is an ancestor. For visible trails, the view supplies dynamic ancestor links and localized text, and registered IBreadcrumbProvider implementations can postprocess only those ancestors. The helper preserves their final list order and appends the normalized title as the final, unlinked current node. Hidden admin trails use only the explicit title and skip children and providers entirely. On the admin, the trail appears above a heading containing that text; on the front end, no heading is rendered by default.

Keep built-in views inline, with the current page in title rather than a child. Use lightweight providers for shared or cross-module ancestor changes, not a separate manager, builder, named-provider base class, or contextual-data contract. Customize the owning view or its partials for the title and screen-specific ancestors, and use shape alternates for presentation. INavigationProvider remains the separate extension point for ordinary navigation menus.

Keep all Show breadcrumb logic in the tag helper. Views and partials must not read AdminSettings.ShowBreadcrumb or gate lookups, child declarations, or breadcrumb markup on it. Declare nodes and resolve needed data normally; the helper alone chooses visibility and the provider/title pipeline.

Mental model

1. Require a stable name and a non-null Microsoft.AspNetCore.Html.IHtmlContent title, including LocalizedHtmlString. Empty content such as HtmlString.Empty suppresses heading/browser-title text but still leaves a current node in a visible trail.
2. Check visibility before any child or provider work. A hidden admin trail never calls GetChildContentAsync, resolves or enumerates providers, constructs or invokes them, or creates a BreadcrumbContext or any breadcrumb items, including the current node.
3. For a hidden trail, only the explicit title matters. When heading or browser-title output is needed, call WriteTo(writer, HtmlEncoder.Default) once and HTML-decode once, then safely encode the text for output. With heading="" and page-title="false", validate the non-null title but also skip WriteTo.
4. For a visible trail, normalize the title, collect ancestor children, and await registered providers sequentially in DI registration order on the shared mutable ancestor list. Helper-created provider contexts always have ShowTrail == true.
5. Preserve the providers' final ancestor list order without sorting, then unconditionally append the explicit title node with fixed Id = "Title", last/current and never linked. Clearing or reordering ancestors cannot remove or displace it.
6. Visible trails finalize ancestor links and render shapes. Hidden trails render only the requested explicit heading/browser title, with no URL generation, permission lookup, link authorization, or shapes. The admin setting does not affect front-end trails.

Naming

• Use stable literal strings directly in .cshtml: name="ContentsEdit" and ancestor id="Contents".
• Use name for provider targeting, the trail's CSS class, shape alternates, and name-based deduplication, including Dashboard. The current node automatically has Id = "Title"; its name-specific alternate needs no separate attribute.
• Reuse a screen's admin list name when it has one. The content items list uses Contents.
• Prefer PascalCase names without separators so shape alternate file names remain readable.
• Do not introduce breadcrumb constants classes, contextual-data keys, or a data attribute.
• Ancestor IDs and the automatic current-node ID Title identify node shape alternates; they are not rendered as HTML id attributes.

Workflow A: add a breadcrumb to a view

Step 1: Import the tag helpers

Reference OrchardCore.Navigation.Core and add this to the module's Views/_ViewImports.cshtml if it is not already imported:

@addTagHelper *, OrchardCore.Navigation.Core

The always-enabled OrchardCore.Navigation module supplies the shapes. Inline authoring needs no custom provider registration.

Step 2: Declare the explicit title and ancestor children

<zone Name="Title">
    <breadcrumb name="RecordsEdit" title="@T["Edit {0}", record.Name]">
        <breadcrumb-item id="Records" action="Index" controller="Record" area="My.Module" permission="@MyPermissions.ManageRecords.Name">@T["Records"]</breadcrumb-item>
    </breadcrumb>
</zone>

Prefer paired parent tags with inline ancestors. The parent supplies the current page through title; the helper appends it with ID Title. Do not add a duplicate current-page child.

Pass the normal Razor localizer result directly, as with RenderTitleSegments: title="@T["Edit Record"]" or title="@T["Edit {0}", record.Name]". The helper renders the HTML-aware value when needed, including its formatting arguments. Do not extract .Value from T[...] or add caller conversions. Keep @T["..."] for ancestor child text too.

Plain strings require the existing safe wrapper new OrchardCore.DisplayManagement.Html.HtmlContentString(value ?? string.Empty). For Microsoft.Extensions.Localization.LocalizedString and OrchardCore.Localization.Data.DataLocalizedString from IDataLocalizer, wrap .Value ?? string.Empty. Do not pass these non-HTML values directly, extract T[...].Value, or use Html.Raw: HtmlContentString encodes untrusted strings when written.

A self-closing helper still requires both attributes, for example <breadcrumb name="Example" title="@T["Edit Example"]" />. Providers may supply ancestors, but not the current title. With no ancestors, a visible trail still contains the appended current node.

Title normalization

With @using OrchardCore.DisplayManagement.Html, prepare the view's values as follows:

Use title="@Microsoft.AspNetCore.Html.HtmlString.Empty" for intentionally empty content. A null title is invalid, including on the no-output path.

When needed, every title follows the same normalization: render its IHtmlContent once with WriteTo(writer, HtmlEncoder.Default), then HTML-decode once into plain text. The helper safely encodes that string for the heading, current node, and browser title. Literal & in a string wrapped with HtmlContentString stays literal &, serialized as & in HTML. Do not pre-encode the wrapper's input. IHtmlContent does not enable arbitrary title markup: final title output remains text-only.

Step 3: Remove duplicate title output

Remove the view's old page heading and RenderTitleSegments call. The helper supplies both by default on the admin. Keep the helper in the Title zone so it works with the admin theme's top-bar title setting.

For a trail that does not own the heading, use the Breadcrumbs zone and heading="". Also set page-title="false" if the page registers its browser title separately.

Child attributes and link behavior

The inner content is localized ancestor text, for example @T["Records"]. Child content is HTML-decoded after Razor evaluates it, then safely encoded by the shape template. The parent's IHtmlContent title is rendered and decoded once as described above. Templates safely encode normalized title and provider-supplied text; do not emit them with Html.Raw.

Every child and provider item remains an ancestor, including the last item in the list. The helper appends a separate title node after all ancestors; only that node is current and never linked. Ancestors with denied permissions, link-enabled="false", or no link target remain visible as text. Do not omit ancestors solely because the user cannot follow their links.

Children and providers only store named permissions. The helper resolves PermissionName after providers and link-eligibility checks, so removed or unlinkable ancestors do not cause a name lookup. The explicit title node never needs link processing. Providers can also add Permission objects to BreadcrumbItem.Permissions; authorization evaluates applicable permissions against Resource. Hidden trails perform neither permission lookup nor authorization.

Workflow B: resolve a nested editor's parent

Use the real parent's display name and route ID, obtained from the view model when available. For example, a model exposing Parent and Record can render:

<zone Name="Title">
    <breadcrumb name="RecordsEdit" title="@T["Edit {0}", Model.Record.Name]">
        <breadcrumb-item id="Records" action="Index" controller="Record" area="My.Module" permission="@MyPermissions.ManageRecords.Name">@T["Records"]</breadcrumb-item>
        <breadcrumb-item id="Parent" action="Edit" controller="Record" area="My.Module"
                         route-id="@Model.Parent.Id"
                         permission="@MyPermissions.ManageRecords.Name"
                         resource="@Model.Parent">@T["Edit {0}", Model.Parent.Name]</breadcrumb-item>
    </breadcrumb>
</zone>

If only the parent ID is available, inject an existing domain service into Razor, not a breadcrumb-specific service. A model with ParentContentItemId, for example, can use:

@inject OrchardCore.ContentManagement.IContentManager ContentManager
@{
    var parent = await ContentManager.GetAsync(Model.ParentContentItemId);
}

Use the loaded parent's ID and display text in ancestor child items. Follow the screen's existing missing-parent handling and error reporting. Do not guard parent lookups on the breadcrumb visibility setting. Hidden trails always skip child content, but parent attribute expressions and Razor code or model lookups outside that child content still execute.

Workflow C: postprocess a trail with a provider

Implement OrchardCore.Navigation.IBreadcrumbProvider:

public interface IBreadcrumbProvider
{
    ValueTask BuildBreadcrumbAsync(BreadcrumbContext context);
}

BreadcrumbContext is also in OrchardCore.Navigation. Its public constructor is BreadcrumbContext(string name, string title, List<BreadcrumbItem> items, ViewContext viewContext, bool showTrail), with ViewContext from Microsoft.AspNetCore.Mvc.Rendering. The helper passes the normalized plain-string title, not the original IHtmlContent. It exposes read-only properties:

Providers see all visible trails unless they explicitly filter the context. This example targets names starting with Example, excluding the Examples list itself by name rather than localized title text:

using System;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.Extensions.Localization;
using OrchardCore.Navigation;

public sealed class ExampleBreadcrumbProvider : IBreadcrumbProvider
{
    private readonly IStringLocalizer S;

    public ExampleBreadcrumbProvider(IStringLocalizer<ExampleBreadcrumbProvider> localizer)
    {
        S = localizer;
    }

    public ValueTask BuildBreadcrumbAsync(BreadcrumbContext context)
    {
        if (!context.Name.StartsWith("Example", StringComparison.Ordinal) || context.Name == "Examples" ||
            context.Items.Any(item => item.Id == "Examples"))
        {
            return ValueTask.CompletedTask;
        }

        context.Items.Insert(0, new BreadcrumbItem
        {
            Id = "Examples",
            Text = S["Examples"].Value,
            Url = "~/examples",
        });

        return ValueTask.CompletedTask;
    }
}

Register the provider in Startup.ConfigureServices:

services.AddBreadcrumbProvider<ExampleBreadcrumbProvider>();

Registration is scoped and uses TryAddEnumerable. For visible trails, providers run in DI registration order after collecting ancestor children, before appending the explicit current node and finalizing IsCurrent and Href. Later providers observe earlier ancestor mutations, and the helper preserves the final list order.

Use context.Name to target a trail, or context.ViewContext to target a request. An admin-only provider checks AdminAttribute.IsApplied(context.ViewContext.HttpContext). Set Text to a plain string, not encoded HTML; use Url or RouteValues, PermissionName or the Permissions list, Resource, and LinkEnabled to describe links. Do not depend on incoming IsCurrent or Href, which the helper computes afterward.

The example also supplies an ancestor to a trail with no inline children. The view must still provide its title:

<breadcrumb name="Example" title="@T["Edit Example"]" />

Providers cannot remove or replace the explicit title: Title is read-only, and Items contains only ancestors. The helper appends the title node with Id = "Title" after all providers have run, even if a provider cleared or reordered every ancestor.

Hidden admin trails bypass providers completely: the helper does not resolve, enumerate, construct, or invoke IBreadcrumbProvider implementations. It creates no BreadcrumbContext; the retained ShowTrail property and constructor parameter are always true in helper-created provider contexts. Only the explicit title supplies hidden heading/browser-title output.