Breadcrumbs

Breadcrumbs help to expose the hierarchy, not the particular clicks of a user. Its logic is more clear and most of it is only in one Mixin, not scattered throughout the code.

Table of Contents

• Usage
  • Breadcrumbs
• Structure
  • Non-explorer controllers
    • Default list
    • Detail
    • Action
  • Explorer controllers
    • Default + detail view
    • Action
• Design
• Examples
  • 1) Explorer screens
  • 2) Non-explorer screens

Usage

Breadcrumbs are automatically generated from information collected in the controller. To allow generating the breadcrumbs, a controller should include Breadcrumbs mixins:

include Mixins::BreadcrumbMixin

and then it has to define a new method which returns a hash with variables depended on the controller and its type.

def breadcrumbs_options
    {
    :breadcrumbs    => ...,
    :include_record => ...,
    :record_info    => ...,
    :record_title   => ...,
    }
end

option	type	default	type of controller	description
:breadcrumbs	array	required	all	Initial sets of breadcrumbs. Should include the menu path.
:record_info	hash	@record	both	Object where current shown record is stored.
:record_title	symbol	:name	both	Attribute of the :record_info object, which will be used as a title in breadcrumbs.
:include_record	bool	false	both	Will use :record_info for creating the item breadcrumb.
:hide_title	bool	false	non-explorer	Will not append @title to breadcrumbs.
:ancestry	Class	nil	explorer	Parent class for ancestry. Used in service controller
:not_tree	bool	false	explorer	This will told the breadcrumb mixin that the controller is not explorer. It should be used in controllers used in more places which someones do not use the explorer presenter.
:disable_tree	bool	false	explorer	Will disable all links in breadcrumbs.
:to_explorer	string	nil	explorer	Link to the explorer page. Will be appended to the penultimate breadcrumb when :disable_tree is set.
:x_node	string	x_node	explorer	Use custom node id instead of default x_node.

Breadcrumbs

{
:breadcrumbs => [
  { :title => ... , :url => ?, :key => ? }
  ]
}

Array of hashes which sets a way in the main navigation menu:

Hash is consisted of:

{
    :title  => _('Cloud Providers'), # Title of the breadcrumb
    :url    => controller_url,       # URL to the controller
    :key    => 'root',               # ID in the tree view, only explorer controllers
}

Structure

Non-explorer controllers

Non-explorer controllers should have this structure:

show_list > show > action

• On show_list the title is not appended, because the title from the menu path is used.
• On show the :record_info is not use by default, because the @title of the page serves as a title in the last breadcrumb.
• On action the :record_info is used to generate item breadcrumb and @title is used as a action breadcrumb.

Default list

[MENU]

ex. Compute > Infrastructure > Hosts / Nodes

When the title of the page is different from the last item in the main navigation, as the breadcrumb title the navigation title is used.

Detail

[MENU] > [ITEM TITLE]

ex. Compute > Infrastructure > Hosts / Nodes > 17d6ec2e-0e75-45ab-95a6-642eb41855cd (Controller) (Summary)

The whole title is used (with Summary, Dashboard)

Action

[MENU] > [ITEM TITLE] > [ACTION HEADER]

ex. Compute > Infrastructure > Hosts / Nodes > 17d6ec2e-0e75-45ab-95a6-642eb41855cd (Controller) > Info/Settings

Notice the item title is no without the appendix. That is correct.

Breadcrumbs should not be deeper than this.

Explorer controllers

Default + detail view

[MENU] > [ACCORDION TITLE] > [CURRENT NODE TEXT]

ex. Compute > Infrastructure > Virtual Machines > VMs & Templates > All VMs & Templates

Accordion title should lead to the tree's root.

! Breadcrumbs do not contain the whole tree path currently !

Action

[MENU] > [ACCORDION TITLE] > [CURRENT NODE TEXT] > [ACTION TITLE]

ex. Compute > Infrastructure > Virtual Machines > VMs & Templates > 3.9ocp > Editing Virtual Machine "3.9ocp"

As a action title it used either of (sorted by the highest priority):

• right_cell_text as a local variable provided to breadcrumbs template (if you provide it in replace_right_cell method)
• @title_for_breadcrumbs (non standard use)
• @right_cell_text (standard use)
• @title (explorer controller switched to non-explorer)

Breadcrumbs should not be deeper than this.

Design

• this design follows Patternfly guidelines
• First, show the path from the navigation (E.g.: Compute > Infrastructure > Providers)
• Only breadcrumbs which lead somewhere should be clickable (last breadcrumb in the menu, etc.)
• The end of the breadcrumb string should represent the page a user is currently viewing
• When using breadcrumbs, be sure to include them on every page throughout the application.
  • Exception: when content is shown on in a separate window without navigation (ex. reports), breadcrumbs are not required

Examples

1) Explorer screens

Default

Detail

Action

Tagging/Ownership/etc.

• Show the item breadcrumb only when there is only one item

One item

More items

Ancestry

• only Services. Services are missing hierarchy in the tree (because of performance).

2) Non-explorer screens

Default

• There could be a different header on the landing page - that is a longer version of the item in the menu. Breadcrumbs should contain the same name as in the menu - the shorter version.

Detail

Detail Action/Action

Tagging/Ownership/etc.

• Show item breadcrumb only when there is only one item

One item

More items