Use Macros

These macros will help you to generate Bootstrap-markup codes quickly and easily.

render_nav_item()

Render a Bootstrap nav item.

Example

{% from 'bootstrap/nav.html' import render_nav_item %}

<nav class="navbar navbar-expand-lg navbar-light bg-light">
    <div class="navbar-nav mr-auto">
        {{ render_nav_item('index', 'Home') }}
        {{ render_nav_item('explore', 'Explore') }}
        {{ render_nav_item('about', 'About') }}
    </div>
</nav>

API

render_nav_item(endpoint, text, badge='', use_li=False, **kwargs)
Parameters:
  • endpoint – The endpoint used to generate URL.
  • text – The text that will displayed on the item.
  • badge – Badge text.
  • use_li – Default to generate <a></a>, if set to True, it will generate <li><a></a></li>.
  • kwargs – Additional keyword arguments pass to url_for().

render_breadcrumb_item()

Render a Bootstrap breadcrumb item.

Example

{% from 'bootstrap/nav.html' import render_breadcrumb_item %}

<nav aria-label="breadcrumb">
    <ol class="breadcrumb">
        {{ render_breadcrumb_item('home', 'Home') }}
        {{ render_breadcrumb_item('users', 'Users') }}
        {{ render_breadcrumb_item('posts', 'Posts') }}
        {{ render_breadcrumb_item('comments', 'Comments') }}
    </ol>
</nav>

API

render_breadcrumb_item(endpoint, text, **kwargs)
Parameters:
  • endpoint – The endpoint used to generate URL.
  • text – The text that will displayed on the item.
  • kwargs – Additional keyword arguments pass to url_for().

render_field()

Render a form input for form field created by Flask-WTF/WTForms.

Example

{% from 'bootstrap/form.html' import render_field %}

<form method="post">
    {{ form.csrf_token() }}
    {{ render_field(form.username) }}
    {{ render_field(form.password) }}
    {{ render_field(form.submit) }}
</form>

API

render_field(field, form_type="basic", horizontal_columns=('lg', 2, 10), button_style="", button_size="", button_map={})
Parameters:
  • field – The form field (attribute) to render.
  • form_type – One of basic, inline or horizontal. See the Bootstrap docs for details on different form layouts.
  • 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).
  • button_style – Accept Bootstrap button style name (i.e. primary, secondary, outline-success, etc.), default to secondary (e.g. btn-secondary). This will overwrite config BOOTSTRAP_BTN_STYLE.
  • button_size – Accept Bootstrap button size name: sm, md, lg, block, default to md. This will overwrite config BOOTSTRAP_BTN_SIZE.
  • 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.

Tip

See Form Button Customization to learn how to customize form buttons.

render_form()

Render a complete form element for form object created by Flask-WTF/WTForms.

Example

{% from 'bootstrap/form.html' import render_form %}

{{ render_form(form) }}

API

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={})
Parameters:
  • form – The form to output.
  • action – The URL to receive form data.
  • method<form> method attribute.
  • extra_classes – The classes to add to the <form>.
  • role<form> role attribute.
  • form_type – One of basic, inline or horizontal. See the Bootstrap docs for details on different form layouts.
  • 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).
  • enctype<form> enctype attribute. If None, will automatically be set to multipart/form-data if a FileField or MultipleFileField is present in the form.
  • button_style – Accept Bootstrap button style name (i.e. primary, secondary, outline-success, etc.), default to secondary (e.g. btn-secondary). This will overwrite config BOOTSTRAP_BTN_STYLE.
  • button_size – Accept Bootstrap button size name: sm, md, lg, block, default to md. This will overwrite config BOOTSTRAP_BTN_SIZE.
  • 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.
  • id – The <form> id attribute.
  • novalidate – Flag that decide whether add novalidate class in <form>.
  • render_kw – A dictionary, specifying custom attributes for the <form> tag.

Tip

See Form Button Customization to learn how to customize form buttons.

render_hidden_errors()

Render error messages for hidden form field (wtforms.HiddenField).

Example

{% from 'bootstrap/form.html' import render_field, render_hidden_errors %}

<form method="post">
    {{ form.hidden_tag() }}
    {{ render_hidden_errors(form) }}
    {{ render_field(form.username) }}
    {{ render_field(form.password) }}
    {{ render_field(form.submit) }}
</form>

API

render_hidden_errors(form)
Parameters:form – Form whose errors should be rendered.

render_form_row()

Render a row of a grid form with the given fields.

Example

{% from 'bootstrap/form.html' import render_form_row %}

<form method="post">
    {{ form.csrf_token() }}
    {{ render_form_row([form.username, form.password]) }}
    {{ render_form_row([form.remember]) }}
    {{ render_form_row([form.submit]) }}
    {# Custom col which should use class col-md-2, and the others the defaults: #}
    {{ render_form_row([form.title, form.first_name, form.surname], col_map={'title': 'col-md-2'}) }}
    {# Custom col which should use class col-md-2 and modified col class for the default of the other fields: #}
    {{ render_form_row([form.title, form.first_name, form.surname], col_class_default='col-md-5', col_map={'title': 'col-md-2'}) }}
</form>

API

render_form_row(fields, row_class='form-row', col_class_default='col', col_map={}, button_style="", button_size="", button_map={})
Parameters:
  • fields – An iterable of fields to render in a row.
  • row_class – Class to apply to the div intended to represent the row, like form-row or row
  • 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.
  • 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'})
  • button_style – Accept Bootstrap button style name (i.e. primary, secondary, outline-success, etc.), default to secondary (e.g. btn-secondary). This will overwrite config BOOTSTRAP_BTN_STYLE.
  • button_size – Accept Bootstrap button size name: sm, md, lg, block, default to md. This will overwrite config BOOTSTRAP_BTN_SIZE.
  • 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.

Tip

See Form Button Customization to learn how to customize form buttons.

render_pager()

Render a simple pager for query pagination object created by Flask-SQLAlchemy.

Example

{% from 'bootstrap/pagination.html' import render_pager %}

{{ render_pager(pagination) }}

API

render_pager(pagination, fragment='', prev=('<span aria-hidden="true">&larr;</span> Previous')|safe, next=('Next <span aria-hidden="true">&rarr;</span>')|safe, align='', **kwargs)
Parameters:
  • paginationPagination instance.
  • fragment – Add URL fragment into link, such as #comment.
  • prev – Symbol/text to use for the “previous page” button.
  • next – Symbol/text to use for the “next page” button.
  • align – Can be ‘left’, ‘center’ or ‘right’, default to ‘left’.
  • kwargs – Additional arguments passed to url_for.

render_pagination()

Render a standard pagination for query pagination object created by Flask-SQLAlchemy.

Example

{% from 'bootstrap/pagination.html' import render_pagination %}

{{ render_pagination(pagination) }}

API

render_pagination(pagination, endpoint=None, prev='«', next='»', ellipses='…', size=None, args={}, fragment='', align='', **kwargs)
Parameters:
  • paginationPagination instance.
  • endpoint – Which endpoint to call when a page number is clicked. url_for() will be called with the given endpoint and a single parameter, page. If None, uses the requests current endpoint.
  • prev – Symbol/text to use for the “previous page” button. If None, the button will be hidden.
  • next – Symbol/text to use for the “next page” button. If None, the button will be hidden.
  • ellipses – Symbol/text to use to indicate that pages have been skipped. If None, no indicator will be printed.
  • size – Can be ‘sm’ or ‘lg’ for smaller/larger pagination.
  • args – Additional arguments passed to url_for(). If endpoint is None, uses args and view_args
  • fragment – Add URL fragment into link, such as #comment.
  • align – The align of the pagination. Can be ‘left’, ‘center’ or ‘right’, default to ‘left’.
  • kwargs – Extra attributes for the <ul>-element.

render_static()

Render a resource reference code (i.e. <link>, <script>).

Example

{% from 'bootstrap/utils.html' import render_static %}

{{ render_static('css', 'style.css') }}

API

render_static(type, filename_or_url, local=True)
Parameters:
  • type – Resources type, one of css, js, icon.
  • filename_or_url – The name of the file, or the full URL when local set to False.
  • local – Load local resources or from the passed URL.

render_messages()

Render Bootstrap alerts for flash messages send by flask.flash().

Example

Flash the message in your view function with flash(message, category):

from flask import flash

@app.route('/test')
def test():
    flash('a info message', 'info')
    flash('a danger message', 'danger')
    return your_template

Render the messages in your base template (normally below the navbar):

{% from 'bootstrap/utils.html' import render_messages %}

<nav>...</nav>
{{ render_messages() }}
<main>...</main>

API

render_messages(messages=None, container=False, transform={...}, default_category=config.BOOTSTRAP_MSG_CATEGORY, dismissible=False, dismiss_animate=False)
Parameters:
  • messages – The messages to show. If not given, default to get from flask.get_flashed_messages(with_categories=True).
  • container – If true, will output a complete <div class="container"> element, otherwise just the messages each wrapped in a <div>.
  • transform – A dictionary of mappings for categories. Will be looked up case-insensitively. Default maps all Python loglevel names to Bootstrap CSS classes.
  • default_category – If a category does not has a mapping in transform, it is passed through unchanged. default_category will be used when category is empty.
  • dismissible – If true, will output a button to close an alert. For fully functioning dismissible alerts, you must use the alerts JavaScript plugin.
  • dismiss_animate – If true, will enable dismiss animate when click the dismiss button.

When you call flash('message', 'category'), there are 8 category options available, mapping to Bootstrap 4’s alerts type:

primary, secondary, success, danger, warning, info, light, dark.

If you want to use HTML in your message body, just wrapper your message string with flask.Markup to tell Jinja it’s safe:

from flask import flash, Markup

@app.route('/test')
def test():
    flash(Markup('a info message with a link: <a href="/">Click me!</a>'), 'info')
    return your_template

render_table()

Render a Bootstrap table with given data.

Example

@app.route('/test')
def test():
    data = Message.query.all()
    return render_template('test.html', data=data)
{% from 'bootstrap/table.html' import render_table %}

{{ render_table(data) }}

API

render_table(data, titles=None, primary_key='id', primary_key_title='#', caption=None, table_classes=None, header_classes=None, responsive=False, responsive_class='table-responsive', show_actions=False, actions_title='Actions', model=None, custom_actions=None, view_url=None, edit_url=None, delete_url=None, new_url=None)
Parameters:
  • data – An iterable of data objects to render. Can be dicts or class objects.
  • titles – An iterable of tuples of the format (prop, label) e.g [('id', '#')], if not provided, will automatically detect on provided data, currently only support SQLAlchemy object.
  • primary_key – Primary key identifier for a single row, default to id.
  • primary_key_title – Primary key title for a single row, default to #.
  • caption – A caption to attach to the table.
  • table_classes – A string of classes to apply to the table (e.g 'table-small table-dark').
  • header_classes – A string of classes to apply to the table header (e.g 'thead-dark').
  • responsive – Whether to enable/disable table responsiveness.
  • responsive_class – The responsive class to apply to the table. Default is 'table-responsive'.
  • show_actions – Whether to display the actions column. Default is False.
  • model – The model used to build custom_action, view, edit, delete URLs.
  • actions_title – Title for the actions column header. Default is 'Actions'.
  • custom_actions – A list of tuples for creating custom action buttons, where each tuple contains (‘Title Text displayed on hover’, ‘bootstrap icon name’, ‘URL tuple’) (e.g. [('Run', 'play-fill', ('run_report', [('report_id', ':id')]))]).
  • view_url – URL string or URL tuple in ('endpoint', [('url_parameter_name', ':db_model_fieldname')]) to use for the view action.
  • edit_url – URL string or URL tuple in ('endpoint', [('url_parameter_name', ':db_model_fieldname')]) to use for the edit action.
  • delete_url – URL string or URL tuple in ('endpoint', [('url_parameter_name', ':db_model_fieldname')]) to use for the delete action.
  • new_url – URL string or endpoint to use for the create action (new in version 1.6.0).

To set the URLs for table actions, you will need to pass an URL tuple in the form of ('endpoint', [('url_parameter_name', ':db_model_fieldname')]):

  • endpoint: endpoint of the view, normally the name of the view function
  • [('url_parameter_name', ':db_model_fieldname')]: a list of two-element tuples, the tuple should contain the URL parameter name and the corresponding field name in the database model (starts with a : mark to indicate it’s a variable, otherwise it will becomes a fixed value). db_model_fieldname` may also contain dots to access relationships and their fields (e.g. user.name).

Remember to set the model when setting this URLs, so that Bootstrap-Flask will know where to get the actual value when building the URL.

For example, for the view below:

class Message(Model):
    id = Column(primary_key=True)

@app.route('/messages/<int:message_id>')
def view_message(message_id):
    pass

To pass the URL point to this view for view_url, the value will be: view_url=('view_message', [('message_id', ':id')]). Here is the full example:

@app.route('/test')
def test():
    data = Message.query.all()
    return render_template('test.html', data=data, Message=Message)
{% from 'bootstrap/table.html' import render_table %}

{{ render_table(data, model=Message, view_url=('view_message', [('message_id', ':id')])) }}

The following arguments are expect to accpet an URL tuple:

  • custom_actions
  • view_url
  • edit_url
  • delete_url

You can also pass a fiexd URL string, but use a primary key placeholder in the URL is deprecated and will be removed in version 2.0.

When setting the delete_url, you will also need to enable the CSRFProtect extension provided by Flask-WTF, so that the CSRF protection can be added to the delete button:

$ pip install flask-wtf
from flask_wtf import CSRFProtect

csrf = CSRFProtect(app)

By default, it will enable the CSRF token check for all the POST requests, read more about this extension in its documentation.

render_icon()

Render a Bootstrap icon.

Example

{% from 'bootstrap/utils.html' import render_icon %}

{{ render_icon('heart') }}

API

render_icon(name, size=config.BOOTSTRAP_ICON_SIZE, color=config.BOOTSTRAP_ICON_COLOR)
Parameters:
  • name – The name of icon, you can find all available names at Bootstrap Icon.
  • size – The size of icon, you can pass any vaild size value (e.g. 32/'32px', 1.5em, etc.), default to use configuration BOOTSTRAP_ICON_SIZE (default value is ‘1em’).
  • color – The color of icon, follow the context with currentColor if not set. Accept values are Bootstrap style name (one of ['primary', 'secondary', 'success', 'danger', 'warning', 'info', 'light', 'dark', 'muted']) or any valid color string (e.g. 'red', '#ddd' or '(250, 250, 250)'), default to use configuration BOOTSTRAP_ICON_COLOR (default value is None).