Skip to content

Latest commit

 

History

History
110 lines (80 loc) · 5.07 KB

README.md

File metadata and controls

110 lines (80 loc) · 5.07 KB
Raw

Nuget build

Xperience 13 .NET Core Breadcrumb Widget

This is a widget for Xperience .NET Core websites which use Content Tree-Based routing.

screenshot

Installation

  1. Install the Xperience.Core.Breadcrumbs NuGet package in your .NET Core application
  2. Register the breadcrumbs in your application startup:
using Xperience.Core.Breadcrumbs;

public void ConfigureServices(IServiceCollection services) {
    // Use default properties for all breadcrumbs
    services.AddBreadcrumbs();

    // Or, use these properties for all breadcrumbs
    services.AddBreadcrumbs(options => {
        options.Separator = "|";
        options.ShowContainers = true;
        options.ShowSiteLink = true;
        options.ContainerClass = "breadcrumbs-widget";
        options.BreadcrumbItemClass = "breadcrumb-item";
        options.CurrentPageClass = "breadcrumbs-current";
    });

Using the breadcrumbs

Adding the pagebuilder widget

The breadcrumbs widget can be added to any page which uses the page builder. It has 6 properties:

  • Show domain link first: Displays the site name and a link to the root of the site as the first breadcrumb item
  • Show container page types: If checked, pages that use container page types (e.g. a Folder) will appear in the breadcrumbs
  • Separator: The text to add between each breadcrumb item
  • Container class: The CSS class(es) to add the div that surrounds the breadcrumbs
  • Item class: The CSS class(es) added to all breadcrumb items
  • Current page class: The CSS class(es) add to the current page

Adding breadcrumbs to views

You can also add the widget directly to any view, such as the main Layout.cshtml:

@using Xperience.Core.Breadcrumbs
@inject BreadcrumbHelper breadcrumbHelper
...
@breadcrumbHelper.GetBreadcrumbs()

To override the properties registered during application startup, pass a new BreadcrumbsWidgetProperties instance:

@breadcrumbHelper.GetBreadcrumbs(new BreadcrumbsWidgetProperties()
{
    Separator = "|",
    ShowContainers = true,
    ShowSiteLink = true,
    ContainerClass = "my-breadcrumbs",
    BreadcrumbItemClass = "breadcrumb-item",
    CurrentPageClass = "breadcrumbs-current"
})

Customizations

Breadcrumb rendering

The final HTML of your breadcrumbs is determined by the IBreadcrumbsRenderer interface, which you can find the default code for in DefaultBreadcrumbsRenderer. If you'd like to customize the HTML of the breadcrumbs, you can implement your own IBreadcrumbsRenderer and use the RegisterImplementation attribute to register your code with a higher priority:

[assembly: RegisterImplementation(typeof(IBreadcrumbsRenderer), typeof(CustomBreadcrumbsRenderer), Lifestyle = Lifestyle.Singleton, Priority = RegistrationPriority.Default)]
namespace MySite.Breadcrumbs {
    /// <summary>
    /// Custom implementation of <see cref="IBreadcrumbsRenderer"/>.
    /// </summary>
    public class CustomBreadcrumbsRenderer : IBreadcrumbsRenderer {

Breadcrumb item generation

Breadcrumb items are provided by the DefaultBreadcrumbItemMapper. If you would like to modify how the breadcrumb names, URLs, etc. are generated, you can implement your own IBreadcrumbItemMapper and use the RegisterImplementation attribute to register your code with a higher priority:

[assembly: RegisterImplementation(typeof(IBreadcrumbItemMapper), typeof(CustomBreadcrumbItemMapper), Lifestyle = Lifestyle.Singleton, Priority = RegistrationPriority.Default)]
namespace MySite.Breadcrumbs
{
    /// <summary>
    /// Custom implementation of <see cref="IBreadcrumbItemMapper"/>.
    /// </summary>
    public class CustomBreadcrumbItemMapper : IBreadcrumbItemMapper {

Compatibility

This code is only available for use on Kentico Xperience 13 websites using the .NET Core development model. The website must be using the content tree-based routing model for the breadcrumbs to display properly.

Feedback & Contributing

Check out the contributing page to see the best places to file issues, start discussions, and begin contributing.

License

The repository is available as open source under the terms of the MIT License.