Flask-Breadcrumbs is a Flask extension that adds support for generating site breadcrumb navigation.
Flask-Breadcrumbs is on PyPI so all you need is:
$ pip install Flask-Breadcrumbs
The development version can be downloaded from its page at GitHub.
$ git clone https://github.com/inveniosoftware/flask-breadcrumbs.git
$ cd flask-breadcrumbs
$ python setup.py develop
$ ./run-tests.sh
Flask-Breadcrumbs has the following dependencies:
Flask-Breadcrumbs requires Python version 2.6, 2.7 or 3.3+.
This guide assumes that you have successfully installed Flask-Breadcrumbs package already. If not, please follow the Installation instructions first.
Here is a simple Flask-Breadcrumbs usage example:
from flask import Flask
from flask.ext import breadcrumbs
app = Flask(__name__)
# Initialize Flask-Breadcrumbs
breadcrumbs.Breadcrumbs(app=app)
@app.route('/')
@breadcrumbs.register_breadcrumb(app, '.', 'Home')
def index():
pass
if __name__ == '__main__':
app.run(debug=True)
Save this as app.py and run it using your Python interpreter.
$ python app.py
* Running on http://127.0.0.1:5000/
By default, a proxy object to current_breadcrumbs is added to your Jinja2 context as breadcrumbs to help you with creating navigation bar. For example:
<div>
{%- for breadcrumb in breadcrumbs -%}
<a href="{{ breadcrumb.url }}">{{ breadcrumb.text }}</a>
{{ '/' if not loop.last }}
{%- endfor -%}
</div>
For routes with a variable part, a dynamic list constructor can be used to create a more meaningful breadcrumb. In the example below, the User’s primary key is used to create a breadcrumb displaying their name.
from flask import request, render_template
def view_user_dlc(*args, **kwargs):
user_id = request.view_args['user_id']
user = User.query.get(user_id)
return [{'text': user.name, 'url': user.url}]
@app.route('/users/<int:user_id>')
@breadcrumbs.register_breadcrumb(app, '.user.id', '',
dynamic_list_constructor=view_user_dlc)
def view_user(user_id):
user = User.query.get(user_id)
return render_template('user.html', user=user)
The most import part of an modular Flask application is Blueprint. You can create one for your application somewhere in your code and decorate your view function, like this:
from flask import Blueprint
from flask.ext import breadcrumbs
account = Blueprint('account', __name__, url_prefix='/account')
@account.route('/')
@breadcrumbs.register_breadcrumb(account, '.', 'Your account')
def index():
pass
Sometimes you want to combine multiple blueprints and organize the navigation to certain hierarchy using function default_breadcrumb_root().
from flask import Blueprint
from flask.ext import breadcrumbs
social = Blueprint('social', __name__, url_prefix='/social')
breadcrumbs.default_breadcrumb_root(social, '.account')
@social.route('/list')
@breadcrumbs.register_breadcrumb(social, '.list', 'Social networks')
def list():
pass
As a result of this, your current_breadcrumbs object with contain list with 3 items during processing request for /social/list.
from example import app
from flask.ext import breadcrumbs
import account
import social
app.register_blueprint(account.bp_account)
app.register_blueprint(social.bp_social)
with app.test_client() as c:
c.get('/social/list')
assert map(lambda x: x.url,
list(breadcrumbs.current_breadcrumbs)) == [
'/', '/account/', '/social/list']
If you are looking for information on a specific function, class or method, this part of the documentation is for you.
Breadcrumb organizer for a Flask application.
Backend function for breadcrumbs proxy.
Returns: | A list of breadcrumbs. |
---|
Add variable breadcrumbs to template context.
It contains the list of menu entries to render as breadcrumbs.
Determine current location in menu hierarchy.
Backend function for current_path proxy.
Return path to root of application’s or bluerpint’s branch.
Configure an application. This registers a context_processor.
Parameters: | app (flask.Flask) – The flask.Flask object to configure. |
---|
Decorate endpoints that should be displayed as a breadcrumb.
Parameters: |
|
---|
Register default breadcrumb path for all endpoints in this blueprint.
Parameters: |
|
---|
Here you can see the full list of changes between each Flask-Breadcrumbs release.
Version 0.3.0 (released 2015-03-16)
Version 0.2.0 (released 2014-11-05)
Version 0.1.0 (released 2014-07-24)
Bug reports, feature requests, and other contributions are welcome. If you find a demonstrable problem that is caused by the code of this library, please:
If you create a feature branch, you can run the tests to ensure everything is operating correctly:
$ ./run-tests.sh
Flask-Breadcrumbs is free software; you can redistribute it and/or modify it under the terms of the Revised BSD License quoted below.
Copyright (C) 2013, 2014 CERN.
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
In applying this license, CERN does not waive the privileges and immunities granted to it by virtue of its status as an Intergovernmental Organization or submit itself to any jurisdiction.
Flask-Breadcrumbs is developed for use in Invenio digital library software.
Contact us at info@invenio-software.org