Basic Usage
===========
Installation
------------
.. code-block:: bash
$ pip install bootstrap-flask
This project can't work with Flask-Bootstrap at the same time. If you have already installed Flask-Bootstrap in the same Python enviroment, you have to uninstall it and then reinstall this project:
.. code-block:: bash
$ pip uninstall flask-bootstrap bootstrap-flask
$ pip install bootstrap-flask
.. tip:: See :doc:`migrate` to learn how to migrate from Flask-Bootstrap.
Initialization
--------------
.. code-block:: python
from flask_bootstrap import Bootstrap4
from flask import Flask
app = Flask(__name__)
bootstrap = Bootstrap4(app)
If you want to use Bootstrap 5, import and instanzlize the ``Bootstrap5`` class instead:
.. code-block:: python
from flask_bootstrap import Bootstrap5
from flask import Flask
app = Flask(__name__)
bootstrap = Bootstrap5(app)
Resources Helpers
-----------------
Bootstrap-Flask provides two helper functions to load Bootstrap resources in the template:
``bootstrap.load_css()`` and ``bootstrap.load_js()``.
Call it in your base template, for example:
.. code-block:: jinja
....
{{ bootstrap.load_css() }}
...
{{ bootstrap.load_js() }}
You can pass ``version`` to pin the Bootstrap version you want to use.
It defaults to load files from CDN. Set ``BOOTSTRAP_SERVE_LOCAL``
to ``True`` to use built-in local files. However, these methods are optional, you can also write ````
and ```` tags to include Bootstrap resources (from your ``static`` folder or CDN) manually by yourself.
If you want to apply a strict Content Security Policy (CSP), you can pass ``nonce`` to ``bootstrap.load_js()``.
E.g. if using `Talisman
`_ it can be called with ``bootstrap.load_js(nonce=csp_nonce())``.
Starter template
----------------
For reasons of flexibility, Bootstrap-Flask doesn't include built-in base templates (this may change in the future). For now, you have to create a base template yourself. Be sure to use an HTML5 doctype and include a viewport meta tag for proper responsive behaviors. Here's an example base template:
.. code-block:: html
{% block head %}
{% block styles %}
{{ bootstrap.load_css() }}
{% endblock %}
Your page title
{% endblock %}
{% block content %}{% endblock %}
{% block scripts %}
{{ bootstrap.load_js() }}
{% endblock %}
Use this in your templates folder (suggested names are ``base.html`` or ``layout.html`` etc.), and inherit it in child templates. See `Template Inheritance `_ for more details on inheritance.
.. _macros_list:
Macros
------
+---------------------------+--------------------------------+--------------------------------------------------------------------+
| Macro | Templates Path | Description |
+===========================+================================+====================================================================+
| render_field() | bootstrap4/form.html | Render a WTForms form field |
+---------------------------+--------------------------------+--------------------------------------------------------------------+
| render_form() | bootstrap4/form.html | Render a WTForms form |
+---------------------------+--------------------------------+--------------------------------------------------------------------+
| render_form_row() | bootstrap4/form.html | Render a row of a grid form |
+---------------------------+--------------------------------+--------------------------------------------------------------------+
| render_hidden_errors() | bootstrap4/form.html | Render error messages for hidden form field |
+---------------------------+--------------------------------+--------------------------------------------------------------------+
| render_pager() | bootstrap4/pagination.html | Render a basic Flask-SQLAlchemy pagniantion |
+---------------------------+--------------------------------+--------------------------------------------------------------------+
| render_pagination() | bootstrap4/pagination.html | Render a standard Flask-SQLAlchemy pagination |
+---------------------------+--------------------------------+--------------------------------------------------------------------+
| render_nav_item() | bootstrap4/nav.html | Render a navigation item |
+---------------------------+--------------------------------+--------------------------------------------------------------------+
| render_breadcrumb_item() | bootstrap4/nav.html | Render a breadcrumb item |
+---------------------------+--------------------------------+--------------------------------------------------------------------+
| render_static() | bootstrap4/utils.html | Render a resource reference code (i.e. ````, ``