BreadcrumbBar toturial

BreadcrumbBar.md

BreadcrumbBar

Breadcrumbs display a users location within an application hierarchy. They act as a resource to help users navigate more efficiently and provide additional context.

The Breadcrumb Switcher provides a shortcut for users to quickly navigate to parallel pages, rather than navigating back to the previous page and making a new selection.

Changes

In version 1.18 we have introduced the new BreadcrumbBar that should eventually replace the two-pane navigation.

Notice: the two-pane is deprecated now and will be removed in version 1.19.

How to use it

The easiest way to apply the BreadcrumbBar on your page is to keep using the LayoutHelper::title as you use it today.

# app/views/posts/show.html.erb

<% title("Post 1") %>

It will make the BreadcrumbBar appear in edit and show pages. It will try to match the best set of configurations for the current page and will apply it on the BreadcrumbBar. see app/services/breadcrumbs_options.rb

Override the default configurations

In some cases, the generic configurations won't fit your page, and you will need to set the configurations manually. To do so, you will need to migrate from using the LayoutHelper::title to use the new LayoutHelper::breadcrumbs.

The LayoutHelper::breadcrumbs function will use the same default configurations while you can pass your own configurations as a hash. It will override only the configurations you actually passed.

# app/views/posts/edit.html.erb

<%= breadcrumbs(
    items: [
      {
        caption: "Posts",
        url: "/posts"
      },
      {
        caption: "Edit Post 1"
      }
    ],
    switchable: true,
    name_field: "title",
    resource_url: "/resource-item-url",
    switcher_item_url: "/switcher-item-url-template/:id/edit"
  )
%>

The breadcrumbs_options hash

• nothing is required

Key	Type	Description	Default Value
items	Array(breadcrumb_item)	Breadcrumb items to show	BreadcrumbsOptions::items
switchable	boolean	Whether or not to show the BreadcrumbSwitcher	BreadcrumbsOptions::switchable?
name_field	string	If switchable, the name_field will be the display field from the switcher results	BreadcrumbsOptions::model_name_field
resource_url	string	If switchable, it will be used to fetch switcher items when opening the switcher	"/api/v2/#{controller_name}"
switcher_item_url	string	If switchable, it will be used as a template to create urls for each switcher item. :id will be replaced with the actual id of the switcher item.	BreadcrumbsOptions::switcher_url_template

The breadcrumb_item hash

Key	Type	Description
caption	string	The link text
url	string	The link URL

How to migrate from two-pane to the new BreadcrumbBar

1. Disable the two-pane functionality by removing the table-two-pane class from your index.html.erb file.

-<table class="<%= table_css_classes('table-two-pane table-fixed') %>">
+<table class="<%= table_css_classes('table-fixed') %>">

2. The BreadcumbBar should get mounted to the view when navigating to new/edit/show pages with the default configurations.

3. If the default configurations are not enough, override the needed fields in each view new/edit/show.

+<%= breadcrumbs name_field: 'description' %>

Migration PR examples

• theforeman/foreman_discovery/pull/425
• theforeman/foreman-tasks/pull/330
• theforeman/foreman_remote_execution/pull/344