Breadcrumb.Plugin

Assembly: Breadcrumb.Plugin

Description

Breadcrumbs provide an additional form of navigational aid to users, they can help to inform the user of their current position within the site and provide an additional form of navigation.

The breadcrumb plugin makes it easy to create breadcrumbs within a web application, it works in two ways:

• Attributes are placed on controller methods where a breadcrumb is required.
• Progmatically create breadcrumb items and their heirerarchy whilst processing requests.

However they are used, they follow a very simple form, a breadcrumb can function as both a parent and child to another breadcrumb item. If attribute breadcrumbs are used then the parent of the breadcrumb is also listed, this allows the middleware to build up the breadcrumb heirerarchy which is then inserted into the temp data for the context being processed.

Once the breadcrumb data has been provided to the controller, it can then be extracted and placed within the view model for display within the view.

Localization

The breadcrumb plugin fully supports localizatin, provided that the Localization.Plugin module is also loaded. Whilst building the breadcrumb heirerarchy for the request, the name of the breadcrumb is translated to the current culture specified by the user.

Caching

Page load time is a very important aspect of any website, to ensure that the breadcrumb is delivered in a timely manner the requests are cached for a minimum of 20 minutes after the first request.

Attribute Based Breadcrumbs

The following example, taken from the CompanyPlugin demonstrates adding a breadcrumb to the view which shows the cookie policy.

[Breadcrumb(nameof(Languages.LanguageStrings.Cookies))]
public IActionResult Cookies()
{
    // code removed for brevity
}

When viewing the cookie page, the breadcrumb presented would look like:

Home / Cookies

From the shopping cart plugin, the following example show building a heirerarchy of breadcrumbs.

[HttpGet]
[Breadcrumb(nameof(Languages.LanguageStrings.ShoppingCart))]
public IActionResult Index()
{
    // code removed for brevity
}

[HttpGet]
[Breadcrumb(nameof(Shipping), nameof(CartController), nameof(Index))]
public IActionResult Shipping()
{
    // code removed for brevity
}

[HttpPost]
[Breadcrumb(nameof(Checkout), nameof(CartController), nameof(Shipping))]
public IActionResult Checkout(int? shippingId)
{
    // code removed for brevity
}

In the example above, the Index method of the shopping cart has a simple breadcrumb, with no parent, this will show

Home / Shopping Cart

The next step in the shopping cart is to select the shipping address (if applicable). The breadcrumb for this action method has a name of shipping and the parent points to the Index action method. The breadcrumb for this would look like

Home / Shopping Cart / Shipping

The last example above is the checkout action method, this is the logical step after the delivery address is. The breadcrumb has a parent pointing to the Shipping action method and would look like

Home / Shopping Cart / Shipping / Checkout

If the product does not require shipping we could manually remove the shipping breadcrumb from the list:

if (!cartDetail.RequiresShipping)
    model.Breadcrumbs.RemoveAt(2);

There are more complex cases when working with dynamic data, for this scenario you can use IBreadcrumbService interface. This interface which is available using dependency injection has methods which allows for breadcrumbs to be added dynamically when initialising and will then operate like a standard attribute based breadcrumb item. The following code taken from the SystemAdmin.Plugin demonstrates how the breadcrumbs are generated for dynamic menu items only known at runtime:

private void RegisterBreadcrumbs(in IBreadcrumbService breadcrumbService, 
    in ISystemAdminHelperService systemAdminHelper)
{
    string parentRoute = "/SystemAdmin";
    breadcrumbService.AddBreadcrumb(nameof(Languages.LanguageStrings.SystemAdmin), parentRoute, false);
 
    foreach (SystemAdminMainMenu item in systemAdminHelper.GetSystemAdminMainMenu())
    {
        string route = $"/SystemAdmin/Index/{item.UniqueId}";
        breadcrumbService.AddBreadcrumb(item.Name, route, parentRoute, false);
 
        foreach (SystemAdminSubMenu childItem in item.ChildMenuItems)
        {
            switch (childItem.MenuType())
            {
                case Enums.SystemAdminMenuType.Grid:
                    breadcrumbService.AddBreadcrumb(childItem.Name(), $"/SystemAdmin/Grid/{childItem.UniqueId}", route, false);
                    break;
                case Enums.SystemAdminMenuType.Text:
                    breadcrumbService.AddBreadcrumb(childItem.Name(), $"/SystemAdmin/Text/{childItem.UniqueId}", route, false);
                    break;
                case Enums.SystemAdminMenuType.PartialView:
                    breadcrumbService.AddBreadcrumb(childItem.Name(), $"/SystemAdmin/View/{childItem.UniqueId}", route, false);
                    break;
                case Enums.SystemAdminMenuType.Map:
                    breadcrumbService.AddBreadcrumb(childItem.Name(), $"/SystemAdmin/Map/{childItem.UniqueId}", route, false);
                    break;
                case Enums.SystemAdminMenuType.FormattedText:
                    breadcrumbService.AddBreadcrumb(childItem.Name(), $"/SystemAdmin/TextEx/{childItem.UniqueId}", route, false);
                    break;
            }
 
        }
    }
}

Retreiving Breadcrumb Data

The breadcrumb data that is generated is inserted into the HttpContext.Items for the request and can be easily retrieved by ensuring that the breadcrumbs exists and returning them. BaseController which is a class that any controller can inherit from, contains a method to obtain the breadcrumb data:

protected List<BreadcrumbItem> GetBreadcrumbs()
{
    if (HttpContext.Items.ContainsKey(Constants.Breadcrumbs))
    {
        return (List<BreadcrumbItem>)HttpContext.Items[Constants.Breadcrumbs];
    }
 
    return new List<BreadcrumbItem>();
}

The BaseModel class is a simple class which any view model can inherit from and contains two methods which can be used to retrieve breadcrumb data, the overloaded methods are both called BreadcrumbData .

As can be seen the breadcrumb plugin makes building a breadcrumb heirerarchy very simple indeed, but adds the required flexibility to ensure cope with a vast variety of situations.