Site Breadcrumbs

Breadcrumbs are an informative device which appear on many pages on the site. Breadcrumbs provide the user a sense of location within the site and a way to logically navigate back to the homepage.

A breadcrumb is an ordered collection of crumbs, with each crumb having a title and a link.

Drupal Core Breadcrumb Functionality

Drupal has a built-in breadcrumbs methodology, which will attempt to build out a pathway based on the URI (e.g. /departments/housing/metrolist) defined by the pages (i.e. nodes) URL Alias.

It does not matter if the URL Alias is set manually or automatically, the value shown in the back-end editor form once the node is saved is used to build out the breadcrumb.

The Drupal core process creates the breadcrumb by scanning the path represented by the URI, and testing if a local page exists for each path element. It stops adding crumbs when a path element does not resolve.

FOR EXAMPLE an article is created with a URI (as defined in its URL Alias): /departments/housing/boston/housing-information-in-boston.

When the page is rendered, Drupal scans the articles URI and

• if we have a breadcrumb setting which stipulates that the homepage should always be shown as the first crumb, then a crumb of home with a link to https://site is created, then

• checks if /departments is a valid URI. https://site/departments is a valid URI, so it creates a crumb of "departments" with a link to https://site/departments , then

• checks if /departments/housing is a valid URI. https://site/departments/housing is a valid URI, so it creates a crumb of "housing" with a link to https://site/department/housing , then

• checks if /departments/housing/boston is a valid URI. https://site/departments/housing/boston is NOT a valid URI - there is no page with that name on https://site so the breadcrumb scanner stops evaluating at this point, but

• if we have a breadcrumb setting to display the actual page in the breadcrumb then a final crumb of housing information in boston is added, with no link (because this is the page showing).

The final breadcrumb in this instance would be HOME > DEPARTMENTS > HOUSING > HOUSING INFORMATION IN BOSTON with links on the first 3 crumbs.

When evaluating if a page exists on the site, Drupal only considers URL Aliases and does not check URL Redirects. So in the example above, the boston crumb/link still would not appear in the breadcrumb even if a place_profile page for Boston existed with the URL Alias of /places/boston and a URL Redirect for /departments/housing/boston.

CoB Theme extension for breadcrumbs

Where Drupal core cannot build out its own breadcrumb trail, there is some additional custom code intended to help make a logical breadcrumb.

The custom breadcrumb code only functions when it determines that Drupal has not built out the entire breadcrumb.

If Drupal has been able to build out all parts of the URI path, then the Drupal breadcrumb is used.

Scans Redirects

The custom code scans URL redirects as well as URL Aliases when building out the breadcrumbs.

Care: Redirects which are manually made on the page admin/config/search/redirect are usually considered "external" by default. Breadcrumbs which use an external link may behave unexpectedly when clicked.

Example: the breadcrumb on d8-dev.boston.gov may open a page on www.boston.gov when clicked.

Solution: Do not create redirects for internal (i.e. Drupal hosted) pages on in the admin/config/search/redirect page. Instead create redirects using the redirect function on the "advanced" tab of the editor form for a page.

Custom Replacements

Some URI paths are hard-coded to build specific breadcrumbs.

For example pages which have a URI path starting with government/cabinet . The custom code ignores the "government/cabinets" part of the path and then build the breadcrumb from the remainder of the path.

The custom breadcrumb object is built here: bos_theme/bos_theme.theme::bos_theme_preprocess_breadcrumb()

The breadcrumb is styled here: bos_theme/templates/navigation/breadcrumb.html.twig