Use Macros
==========
These macros will help you to generate Bootstrap-markup codes quickly and easily.
render_nav_item()
------------------
Render a Bootstrap nav item.
Example
~~~~~~~~
.. code-block:: jinja
{% from 'bootstrap4/nav.html' import render_nav_item %}
API
~~~~
.. py:function:: render_nav_item(endpoint, text, _badge='', _use_li=False, **kwargs)
:param endpoint: The endpoint used to generate URL.
:param text: The text that will displayed on the item.
:param _badge: Badge text.
:param _use_li: Default to generate ````, if set to ``True``, it will generate ``
``.
:param kwargs: Additional keyword arguments pass to ``url_for()``.
render_breadcrumb_item()
--------------------------
Render a Bootstrap breadcrumb item.
Example
~~~~~~~~
.. code-block:: jinja
{% from 'bootstrap4/nav.html' import render_breadcrumb_item %}
API
~~~~
.. py:function:: render_breadcrumb_item(endpoint, text, **kwargs)
:param endpoint: The endpoint used to generate URL.
:param text: The text that will displayed on the item.
:param kwargs: Additional keyword arguments pass to ``url_for()``.
render_field()
----------------
Render a form input for form field created by
`Flask-WTF/WTForms `_.
Example
~~~~~~~~
.. code-block:: jinja
{% from 'bootstrap4/form.html' import render_field %}
You can pass any HTTP attributes as extra keyword arguments like ``class`` or ``placeholder``:
Notice that a ``placeholder`` is only allowed by `W3C validation `_
when the input type is ``email``, ``number``, ``password``, ``search``, ``tel``,
``text`` or ``url``. However, it is possible to use a placeholder for input types
such as ``datetime``.
.. code-block:: jinja
{% from 'bootstrap4/form.html' import render_field %}
Notice the ``class`` value here will overwrite the ``render_kw={'class': '...'}`` you defined in
the form class. Bootstrap-Flask will combine the class value you passed with the ``class`` key of
the ``render_kw`` dict or the ``class`` keyword arguments with Bootstrap classes.
API
~~~~
.. py:function:: render_field(field,\
form_type='basic',\
horizontal_columns=('lg', 2, 10),\
button_style='',\
button_size='',\
button_map={},\
form_group_classes='')
:param field: The form field (attribute) to render.
:param form_type: One of ``basic``, ``inline`` or ``horizontal``. See the
Bootstrap docs for details on different form layouts.
:param horizontal_columns: When using the horizontal layout, layout forms
like this. Must be a 3-tuple of ``(column-type,
left-column-size, right-column-size)``.
:param button_style: Set button style for ``SubmitField``. Accept Bootstrap button style name (i.e. primary,
secondary, outline-success, etc.), default to ``primary`` (e.g. ``btn-primary``). This will
overwrite config ``BOOTSTRAP_BTN_STYLE``.
:param button_size: Set button size for ``SubmitField``. Accept Bootstrap button size name: sm, md, lg, block,
default to ``md``. This will overwrite config ``BOOTSTRAP_BTN_SIZE``.
:param form_group_classes: Bootstrap 5 only (``bootstrap5/form.html``). You can use this parameter to change the
form group classes, it will read the config ``BOOTSTRAP_FORM_GROUP_CLASSES`` first
(the default value is ``mb-3``).
.. tip:: See :ref:`button_customization` and :ref:`checkbox_customization` to learn more on customizations.
render_form()
---------------
Render a complete form element for form object created by Flask-WTF/WTForms.
Example
~~~~~~~~
.. code-block:: jinja
{% from 'bootstrap4/form.html' import render_form %}
{{ render_form(form) }}
API
~~~~
.. py:function:: render_form(form,\
action='',\
method='post',\
extra_classes=None,\
role='form',\
form_type='basic',\
horizontal_columns=('lg', 2, 10),\
enctype=None,\
button_style='',\
button_size='',\
button_map={},\
id='',\
novalidate=False,\
render_kw={},\
form_group_classes='',\
form_inline_classes='',)
:param form: The form to output.
:param action: The URL to receive form data.
:param method: ``
API
~~~~
.. py:function:: render_hidden_errors(form)
:param form: Form whose errors should be rendered.
render_form_row()
------------------
Render a row of a grid form with the given fields.
Example
~~~~~~~~
.. code-block:: jinja
{% from 'bootstrap4/form.html' import render_form_row %}
API
~~~~
.. py:function:: render_form_row(fields,\
row_class='row/form-row',\
col_class_default='col',\
col_map={},\
button_style='',\
button_size='',\
button_map={},\
form_group_classes='',\
form_type='basic',\
horizontal_columns=('lg', 2, 10))
:param fields: An iterable of fields to render in a row.
:param row_class: Class to apply to the div intended to represent the row, like ``form-row`` (Bootstrap 4)
or ``row`` (Bootstrap 5).
:param col_class_default: The default class to apply to the div that represents a column
if nothing more specific is said for the div column of the rendered field.
:param col_map: A dictionary, mapping field.name to a class definition that should be applied to
the div column that contains the field. For example: ``col_map={'username': 'col-md-2'})``.
:param button_style: Set button style for ``SubmitField``. Accept Bootstrap button style name (i.e. primary,
secondary, outline-success, etc.), default to ``primary`` (e.g. ``btn-primary``). This will
overwrite config ``BOOTSTRAP_BTN_STYLE``.
:param button_size: Set button size for ``SubmitField``. Accept Bootstrap button size name: sm, md, lg, block,
default to ``md``. This will overwrite config ``BOOTSTRAP_BTN_SIZE``.
:param button_map: A dictionary, mapping button field name to Bootstrap button style names. For example,
``{'submit': 'success'}``. This will overwrite ``button_style`` and ``BOOTSTRAP_BTN_STYLE``.
:param form_group_classes: Bootstrap 5 only (``bootstrap5/form.html``). You can use this parameter to change the
form group classes, it will read the config ``BOOTSTRAP_FORM_GROUP_CLASSES`` first
(the default value is ``mb-3``).
:param form_type: One of ``basic``, ``inline`` or ``horizontal``. See the Bootstrap docs for details on different
form layouts.
:param horizontal_columns: When using the horizontal layout, layout forms like this. Must be a 3-tuple of
``(column-type, left-column-size, right-column-size)``.
.. tip:: See :ref:`button_customization` to learn how to customize form buttons.
render_pager()
-----------------
Render a simple pager for query pagination object created by Flask-SQLAlchemy.
Example
~~~~~~~~
.. code-block:: jinja
{% from 'bootstrap4/pagination.html' import render_pager %}
{{ render_pager(pagination) }}
API
~~~~
.. py:function:: render_pager(pagination,\
fragment='',\
prev=('← Previous')|safe,\
next=('Next →')|safe,\
align='',\
**kwargs)
:param pagination: :class:`~flask_sqlalchemy.Pagination` instance.
:param fragment: Add URL fragment into link, such as ``#comment``.
:param prev: Symbol/text to use for the "previous page" button.
:param next: Symbol/text to use for the "next page" button.
:param align: Can be 'left', 'center' or 'right', default to 'left'.
:param kwargs: Additional arguments passed to ``url_for``.
render_pagination()
--------------------
Render a standard pagination for query pagination object created by Flask-SQLAlchemy.
Example
~~~~~~~~
.. code-block:: jinja
{% from 'bootstrap4/pagination.html' import render_pagination %}
{{ render_pagination(pagination) }}
API
~~~~
.. py:function:: render_pagination(pagination,\
endpoint=None,\
prev='«',\
next='»',\
ellipses='…',\
size=None,\
args={},\
fragment='',\
align='',\
**kwargs)
:param pagination: :class:`~flask_sqlalchemy.Pagination` instance.
:param endpoint: Which endpoint to call when a page number is clicked.
:func:`~flask.url_for` will be called with the given
endpoint and a single parameter, ``page``. If ``None``,
uses the requests current endpoint.
:param prev: Symbol/text to use for the "previous page" button. If
``None``, the button will be hidden.
:param next: Symbol/text to use for the "next page" button. If
``None``, the button will be hidden.
:param ellipses: Symbol/text to use to indicate that pages have been
skipped. If ``None``, no indicator will be printed.
:param size: Can be 'sm' or 'lg' for smaller/larger pagination.
:param args: Additional arguments passed to :func:`~flask.url_for`. If
``endpoint`` is ``None``, uses :attr:`~flask.Request.args` and
:attr:`~flask.Request.view_args`.
:param fragment: Add URL fragment into link, such as ``#comment``.
:param align: The align of the pagination. Can be 'left', 'center' or 'right', default to 'left'.
:param kwargs: Extra attributes for the ``