Bagaar Ember Breadcrumbs

@bagaar/ember-breadcrumbs is built and maintained by Bagaar.

Template based breadcrumb management for Ember applications.

Table of Contents

• Support
• Installation
• Usage
• Usage Inside an Engine
• Contributing
• License

Support

@bagaar/ember-breadcrumbs supports Ember v3.4 and up.

Usage with older versions might work but is not tested and also requires the ember-angle-bracket-invocation-polyfill addon to be installed.

Installation

ember install @bagaar/ember-breadcrumbs

Usage

1. Defining Where You Want the Breadcrumbs to Be Rendered

{{! app/templates/application.hbs }}

<BreadcrumbsContainer
  class="breadcrumbs"
  @itemClass="breadcrumbs__item"
  @linkClass="breadcrumbs__link"
/>

NOTE: It's also possible to render multiple instances of the <BreadcrumbsContainer /> component.

2. Leaving Behind Breadcrumbs

{{! app/templates/foo.hbs }}

<BreadcrumbsItem as |linkClass|>
  <LinkTo @route="foo" class={{linkClass}}>
    Foo
  </LinkTo>
</BreadcrumbsItem>

{{! app/templates/foo/bar.hbs }}

<BreadcrumbsItem as |linkClass|>
  <LinkTo @route="foo.bar" class={{linkClass}}>
    Bar
  </LinkTo>
</BreadcrumbsItem>

NOTE: The <BreadcrumbsItem /> component is responsible for rendering the provided <LinkTo /> component into all instances of the <BreadcrumbsContainer /> component using Ember's {{in-element}} helper.

Advantages

Leaving behind breadcrumbs like this might seem very verbose, but actually it's pretty flexible and has some advantages:

1. Because you leave behind breadcrumbs inside templates, the addon doesn't have to take async model hooks into account.
2. Because you use Ember's <LinkTo /> component to define breadcrumb links, you have complete control over:
   • how you define them (inline vs. block)
   • how they should work (route, dynamic segments, query parameters, ...)
   • how they should look like (text, icons, additional CSS class names, ...)

Rendered Output

The rendered output will be:

<ul class="breadcrumbs">
  <li class="breadcrumbs__item">
    <a class="breadcrumbs__link" href="/foo">Foo</a>
  </li>
  <li class="breadcrumbs__item">
    <a class="breadcrumbs__link" href="/foo/bar">Bar</a>
  </li>
</ul>

3. Styling the Breadcrumbs

The addon doesn't ship with default styling. This should be done inside the consuming project.

4. <BreadcrumbsContainer /> arguments

Name	Description	Type
itemClass	The class(es) that will be added to all child <BreadcrumbsItem /> components	String
linkClass	The class(es) that will be yielded to the <BreadcrumbsItem />'s block content	String

Usage Inside an Engine

1. Add @bagaar/ember-breadcrumbs to Your Engine's dependencies

This will make all @bagaar/ember-breadcrumbs components available inside the engine.

{
  "dependencies": {
    "@bagaar/ember-breadcrumbs": "*"
  }
}

2. Make the breadcrumbs Service Available Inside the Engine

This will make sure that the same instance of the breadcrumbs service is used inside the engine as inside the host application.

// app/app.js

const App = Application.extend({
  // ...
  engines: {
    engineName: {
      dependencies: {
        services: [
          'breadcrumbs'
        ]
      }
    }
  }
});

// lib/engine-name/addon/engine.js

const Eng = Engine.extend({
  // ...
  dependencies: {
    services: [
      'breadcrumbs'
    ]
  }
});

That's it! Now you should be able to leave behind breadcrumbs inside the engine and render them inside the host application.

Contributing

See the Contributing guide for details.

License

This project is licensed under the MIT License.