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

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

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-3.0.tar.gz (9.8 kB view details)

Uploaded Source

Built Distribution

z3c.breadcrumb-3.0-py3-none-any.whl (10.9 kB view details)

Uploaded Python 3

File details

Details for the file z3c.breadcrumb-3.0.tar.gz.

File metadata

  • Download URL: z3c.breadcrumb-3.0.tar.gz
  • Upload date:
  • Size: 9.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.9.16

File hashes

Hashes for z3c.breadcrumb-3.0.tar.gz
Algorithm Hash digest
SHA256 ab93d931140fd935cf77cc3b5d8eaaa4444c22a12ede75c1fc353bcb775a42a5
MD5 e4d7d978784b4d5f34ce8b84ebb3c937
BLAKE2b-256 5b8d016871862c8ff4ac820acfacaf695f22810e7832594750e6f7f42db80ea5

See more details on using hashes here.

File details

Details for the file z3c.breadcrumb-3.0-py3-none-any.whl.

File metadata

  • Download URL: z3c.breadcrumb-3.0-py3-none-any.whl
  • Upload date:
  • Size: 10.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.9.16

File hashes

Hashes for z3c.breadcrumb-3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 83f9635ee56e8b8be2d5eb5016dfaf20deecc2acdf57b122933f1994c945b596
MD5 ce4d5ec5b633d1aa966a6541ff618b5f
BLAKE2b-256 d91cba648c9a52cfb44d94a87ceeee277e15fd76a77aae2e089e2fdfa0c74697

See more details on using hashes here.

Supported by

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