QDCrumbs

A simple, easy to use package for dynamic breadcrumbs on Flask applications.

Check out this project on GitHub and PyPi

Whilst I was creating this website, I decided that I wanted a clean, easy to navegate design, and one of the ways to achieve that was to include breadcrumbs on each page, to show the reader where they are on the website. For a small website, this can somewhat trivially be done manually, by setting up a list of links to preceding pages on each page. That being said, such an approach is tedious and doesn't scale well whatsoever. The solution? Dynamically generated server-side breadcrumbs!

Now, I am aware that a framework to add breadcrumbs already exists, however when trying it out, it unfortunately downgraded my Flask instance and refused to work (it would immediately crash) and included a larger library with features that I don't intend to use (at least not yet). With these things in mind I decided to try implement dynamically generated breadcrumbs myself, thinking it would be quicker than troubleshooting the existing framework. The result: QDCrumbs!

After throwing together a quick script in my main flask app to get them to work with a static webpage, I decided to package it and include support for dynamically generated pages and work inside of Blueprints.

Installing the package

The package can be installed from PyPi using pip.

pip install qdcrumbs

The following examples work both in the main Flask app and within Blueprints.

QDCrumbs itself is not a Blueprint.

Importing qdcrumbs:

from qdcrumbs import qdcrumb

Standard Usage:

    @app.route('/')
            def my_page():
                x = qdcrumb.get_crumbs()
                return render_template('/my_page.html', breadcrumbs=x)
        

With a variable name:

    @app.route('/path/to/<var>')
            def my_page(var):
                x = qdcrumb.get_crumbs(var)
                return render_template(f'/path/to/{var}.html', breadcrumbs=x)
        

Basic jinja2 template usage:

    <div>
        <!--
            Include a static link to the site root (Index.html)
            (The Application's root must be added manually)
        -->
        <a href="{{ url_for('index.html')}}">Index</a>
        <!--Loop through the breadcrumbs to this resource-->
        {%- for breadcrumb in breadcrumbs -%}
        <a href="{{ breadcrumb.url }}"> / {{ breadcrumb.text }}</a>
        {%- endfor -%}
    </div>
        

For more, check out the GitHub page!

The package was originally thrown together in order to get a prototype working. At first I had no intention to package the software until I ran into the issues of dynamically generated routes and Blueprints. I decided that it may be of use to someone besides myself that wants a quick and easy to use breadcrumb feature for their website.

As it is now, the project isn't exactly quick or dirty, all things considered. Is it the most elegant solution? Probably not. Does it do what it says on the tin? Yes. If you find any use in this package, let me know! I'm interested to know if anyone gets any use out of it.

If you have a request for features or find any bugs, either report a bug on GitHub or send an email to [email protected].

The package is distributed under the MIT license.