Skip to main content

A pluggable breadcrumbs implementation based on adapters.

Project description

The z3c.breadcrumb package provides base classes for breadcrumb implementations. It allows you to write adapters for each content object which provides it’s own rules for providing the breadcrumb name, url and selection.

Detailed Documentation

README

The z3c.breadcrumb package provides base classes for breadcrumb implementations. It allows you to write adapters for each content object which provides it’s own rule for providing the breadcrumb name, url and selection.

Let’s do some imports we will use later.

>>> import zope.interface
>>> import zope.component
>>> from zope.publisher.interfaces.http import IHTTPRequest
>>> from zope.publisher.browser import TestRequest
>>> from zope.traversing.browser import absoluteURL
>>> from zope.container import contained
>>> from z3c.breadcrumb import interfaces
>>> from z3c.breadcrumb import browser

IBreadcrumb

Let’s define a interface and a content object.

>>> class IOffice(zope.interface.Interface):
...     """Office interface."""
>>> @zope.interface.implementer(IOffice)
... class Office(contained.Contained):
...     def __init__(self, label):
...         self.label = label
...         self.activeURL = True
>>> office = Office('Zope Foundation')
>>> office.__name__ = 'ZF'

There is a generic breadcrumb implementation which is registered by default. If we do not implement a custom IBreadcrumb the generic adapter will return the title or __name__ of the item. Let’s register the default adapter, this is normally done in configure.zcml:

>>> zope.component.provideAdapter(browser.GenericBreadcrumb)

And see what we get:

>>> request = TestRequest()
>>> breadcrumb = zope.component.getMultiAdapter((office, request),
...     interfaces.IBreadcrumb)
>>> breadcrumb.name
'ZF'

We can also implement a custom IBreadcrumb adapter and provide another name for the breadcrumb name:

>>> @zope.interface.implementer(interfaces.IBreadcrumb)
... @zope.component.adapter(IOffice, IHTTPRequest)
... class BreadcrumbForOffice(object):
...
...     def __init__(self, context, request):
...         self.context = context
...         self.request = request
...
...     @property
...     def name(self):
...         return self.context.label
...
...     @property
...     def url(self):
...         return absoluteURL(self.context, self.request)
...
...     @property
...     def activeURL(self):
...         return self.context.activeURL

Let’s register the custom IBreadcrumb adapter for IOffice:

>>> zope.component.provideAdapter(BreadcrumbForOffice)

And check the new breadcrumb name:

>>> breadcrumb = zope.component.getMultiAdapter((office, request),
...     interfaces.IBreadcrumb)
>>> breadcrumb.name
'Zope Foundation'

CustomNameBreadcrumb

Let’s define another interface and a content object.

>>> class IOfficeContainer(zope.interface.Interface):
...     """Container of offices."""
>>> @zope.interface.implementer(IOfficeContainer)
... class OfficeContainer(contained.Contained):
...     pass
>>> offices = OfficeContainer()
>>> offices.__name__ = 'offices'

If the custom name for this kind of object is always the same it would quickly get tedious to write a full IBreadcrumb implementation. As a shortcut you can use CustomNameBreadcrumb to get an adapter that acts like GenericBreadcrumb, but returns the name you want.

>>> adapter = browser.CustomNameBreadcrumb('Offices')
>>> adapter
<class 'z3c.breadcrumb.browser.CustomNameBreadcrumb('Offices')'>
>>> zope.component.provideAdapter(adapter,
...     adapts=(IOfficeContainer, IHTTPRequest))
>>> breadcrumb = zope.component.getMultiAdapter((offices, request),
...     interfaces.IBreadcrumb)
>>> breadcrumb.name
'Offices'

IBreadcrumbs

There is also a IBreadcrumbs adapter which knows how to collect breadcrumb informations for each item he traverses. We need to setup a little bit of infrastructure:

>>> root = rootFolder
>>> root['office'] = office

Register the IBreadcrumbs adapter:

>>> zope.component.provideAdapter(browser.Breadcrumbs,
...     (zope.interface.Interface, zope.interface.Interface),
...     interfaces.IBreadcrumbs)

Now we can collect breadcrumbs for our items. You can see the url is correct and the label Zope Foundation is collected by the custom IBreadcrumb adapter:

>>> breadcrumbs = zope.component.getMultiAdapter((office, request),
...     interfaces.IBreadcrumbs)
>>> from pprint import pprint
>>> pprint(list(breadcrumbs.crumbs))
[{'activeURL': True,
  'name': 'top',
  'url': 'http://127.0.0.1'},
 {'activeURL': True,
  'name': 'Zope Foundation',
  'url': 'http://127.0.0.1/office'}]
>>> breadcrumbs.__parent__ is office
True

Default breadcrumbs stops on virtual host root

>>> request._vh_root = office
>>> pprint(list(breadcrumbs.crumbs))
[{'activeURL': True,
  'name': 'Zope Foundation',
  'url': 'http://127.0.0.1'}]

If the breadcrumb of an item is a Null-adapter, then the item is ignored.

>>> from zope.traversing.interfaces import IContainmentRoot
>>> zope.component.provideAdapter(
...     lambda c, r: None,
...     (IContainmentRoot, IHTTPRequest),
...     interfaces.IBreadcrumb)
>>> request = TestRequest()
>>> breadcrumbs = zope.component.getMultiAdapter(
...     (office, request), interfaces.IBreadcrumbs)
>>> pprint(list(breadcrumbs.crumbs))
[{'activeURL': True,
  'name': 'Zope Foundation',
  'url': 'http://127.0.0.1/office'}]

CHANGES

4.0 (2025-04-14)

  • Replace pkg_resources namespace with PEP 420 native namespace.

3.1 (2025-02-14)

  • Add support for Python 3.12, 3.13.

  • Drop support for Python 3.7, 3.8.

3.0 (2023-02-24)

  • Drop support for Python 2.6, 2.7, 3.3, 3.4.

  • Add support for Python 3.7, 3.8, 3.9, 3.10, 3.11.

2.0.0 (2015-11-09)

  • Standardize namespace __init__

2.0.0a1 (2013-02-27)

  • Added support for Python 3.3.

  • Moved zope.app.testing dependency to zope.site.testing.

  • Moved zope.app.container dependency to zope.container.

  • Replaced deprecated zope.interface.implements usage with equivalent zope.interface.implementer decorator.

  • Dropped support for Python 2.4 and 2.5.

1.1.1 (2010-12-12)

  • Added needed but not declated test dependency on zope.app.container.

  • Using Python’s doctest module instead of depreacted zope.testing.doctest.

1.1.0 (2009-05-29)

  • Feature: Added ability to register a Null-adapter as a breadcrumb. A null-breadcrumb will cause the item not to be displayed in the breadcrumbs.

1.0.3 (2008-12-13)

  • Bug: Fixed IBreadcrumbs to match implementation.

  • Clean up dependencies.

1.0.2 (2008-01-23)

  • Bug: Fixed the package’s long description.

  • Feature: Use the correct DocFileSuite class that counts tests properly.

1.0.1 (2007-01-21)

  • Bug: Test coverage brought up to 100%.

  • Feature: Register default IBreadcrumbs adapter.

  • Bug: Default IBreadcrumbs stops only on virtual host root, not on ISite object

1.0.0 (7/10/2007)

  • Initial Release

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

z3c_breadcrumb-4.0.tar.gz (10.6 kB view details)

Uploaded Source

Built Distribution

z3c_breadcrumb-4.0-py3-none-any.whl (10.3 kB view details)

Uploaded Python 3

File details

Details for the file z3c_breadcrumb-4.0.tar.gz.

File metadata

  • Download URL: z3c_breadcrumb-4.0.tar.gz
  • Upload date:
  • Size: 10.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for z3c_breadcrumb-4.0.tar.gz
Algorithm Hash digest
SHA256 d77d62b74be1f75995f9fa734802661bee6e736cc79009ac4f7c32c988f87f92
MD5 fedde03f8833a43b5798d0fddfb4228b
BLAKE2b-256 a0dfb1fa42f2a90cd5a86f7efb1b64f6759702ef0118c3e75d8f680eae26cf95

See more details on using hashes here.

File details

Details for the file z3c_breadcrumb-4.0-py3-none-any.whl.

File metadata

  • Download URL: z3c_breadcrumb-4.0-py3-none-any.whl
  • Upload date:
  • Size: 10.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for z3c_breadcrumb-4.0-py3-none-any.whl
Algorithm Hash digest
SHA256 d5a409fa8e1b3615ec3b79a9c8f8c0af62445eaa8afb7bf7be90fa5c954cbe4d
MD5 9da06b5d6d99726649368677f2116a2b
BLAKE2b-256 7ce642b93abe2c6a8bdaae1e808c3eed75efbd9451855bcc53247f9b699c8ddf

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page