Merge pull request #184 from greyli/render-form-b5

helloflask · Jan 11, 2022 · aee7417 · aee7417
2 parents ff62219 + 4c28263
commit aee7417
Show file tree

Hide file tree

Showing 14 changed files with 528 additions and 59 deletions.
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -11,13 +11,17 @@ Release date: -
 - Combine ``class`` argument of ``render_field`` or ``field.render_kw.class`` with Bootstrap classes
   (`#159 <https://github.com/greyli/bootstrap-flask/pull/159>`__).
 - Add initial support for Bootstrap 5 (`#161 <https://github.com/greyli/bootstrap-flask/pull/161>`__):
-  - Add ``Bootstrap4`` class and deprecate ``Bootstrap``.
-  - Add ``Bootstrap5`` class for Bootstrap 5 support.
-  - Move Bootstrap 4-related files to ``bootstrap4`` subfolder, and deprecate template path ``bootstrap/``.
-  - Bootstrap 4 macros are in the ``bootstrap4/`` template folder, and Bootstrap 5 macros are in ``bootstrap5/``.
-  - Add seperate tests, templates, static files, and examples for Bootstrap 5.
+    - Add ``Bootstrap4`` class and deprecate ``Bootstrap``.
+    - Add ``Bootstrap5`` class for Bootstrap 5 support.
+    - Move Bootstrap 4-related files to ``bootstrap4`` subfolder, and deprecate template path ``bootstrap/``.
+    - Bootstrap 4 macros are in the ``bootstrap4/`` template folder, and Bootstrap 5 macros are in ``bootstrap5/``.
+    - Add separate tests, templates, static files, and examples for Bootstrap 5.
 - Remove the deprecated ``form_errors`` macro and the URL string variable support in ``render_table``.
 - Render boolean field as a Bootstrap switch with ``SwitchField`` class.
+- Add ``BOOTSTRAP_FORM_GROUP_CLASSES`` config for Bootstrap 5, defaults to ``mb-3``. Also add a ``form_group_classes``
+  parameter for ``render_form``, ``render_field``, and ``render_form_row``.
+- Add ``BOOTSTRAP_FORM_INLINE_CLASSES`` config for Bootstrap 5, defaults to ``row row-cols-lg-auto g-3 align-items-center``.
+  Also add a ``form_inline_classes`` parameter for ``render_form``.
 
 
 1.8.0

diff --git a/docs/_templates/sidebarintro.html b/docs/_templates/sidebarintro.html
@@ -1,13 +1,13 @@
-<h3>Bootstrap-Flask</h3>
+<h3><a href="/">Bootstrap-Flask</a></h3>
 <p>
     Bootstrap helper for Flask.
 </p>
 <h3>Links</h3>
 <ul>
-  <li><a href="http://github.com/greyli/bootstrap-flask">GitHub Repository</a></li>
+  <li><a href="https://github.com/greyli/bootstrap-flask">GitHub Repository</a></li>
   <li><a href="https://pypi.org/project/Bootstrap-Flask/">PyPI Releases</a></li>
-  <li><a href="http://github.com/greyli/bootstrap-flask/issues">Issue Tracker</a></li>
-  <li><a href="http://flask.palletsprojects.com/">Flask Documentation</a></li>
+  <li><a href="https://github.com/greyli/bootstrap-flask/issues">Issue Tracker</a></li>
+  <li><a href="https://flask.palletsprojects.com/">Flask Documentation</a></li>
   <li><a href="https://getbootstrap.com/docs/4.6/getting-started/introduction/">Bootstrap 4 Documentation</a></li>
   <li><a href="https://getbootstrap.com/docs/5.1/getting-started/introduction/">Bootstrap 5 Documentation</a></li>
 </ul>
diff --git a/docs/basic.rst b/docs/basic.rst
@@ -153,30 +153,34 @@ Go to the :doc:`macros` page to see the detailed usage for these macros.
 Configurations
 --------------
 
-+-----------------------------+--------------------------------+----------------------------------------------------------------------------------------------+
-| Configuration Variable      | Default Value                  | Description                                                                                  |
-+=============================+================================+==============================================================================================+
-| BOOTSTRAP_SERVE_LOCAL       | ``False``                      | If set to ``True``, local resources will be used for ``load_*`` methods.                     |
-+-----------------------------+--------------------------------+----------------------------------------------------------------------------------------------+
-| BOOTSTRAP_BTN_STYLE         | ``'primary'``                  | Default form button style, will change to ``primary`` in next major release                  |
-+-----------------------------+--------------------------------+----------------------------------------------------------------------------------------------+
-| BOOTSTRAP_BTN_SIZE          | ``'md'``                       | Default form button size                                                                     |
-+-----------------------------+--------------------------------+----------------------------------------------------------------------------------------------+
-| BOOTSTRAP_ICON_SIZE         | ``'1em'``                      | Default icon size                                                                            |
-+-----------------------------+--------------------------------+----------------------------------------------------------------------------------------------+
-| BOOTSTRAP_ICON_COLOR        | ``None``                       | Default icon color, follow the context with ``currentColor`` if not set                      |
-+-----------------------------+--------------------------------+----------------------------------------------------------------------------------------------+
-| BOOTSTRAP_BOOTSWATCH_THEME  | ``None``                       | Bootswatch theme to use, see available themes at :ref:`bootswatch_theme`                     |
-+-----------------------------+--------------------------------+----------------------------------------------------------------------------------------------+
-| BOOTSTRAP_MSG_CATEGORY      | ``'primary'``                  | Default flash message category                                                               |
-+-----------------------------+--------------------------------+----------------------------------------------------------------------------------------------+
-| BOOTSTRAP_TABLE_VIEW_TITLE  | ``'View'``                     | Default title for view icon of table actions                                                 |
-+-----------------------------+--------------------------------+----------------------------------------------------------------------------------------------+
-| BOOTSTRAP_TABLE_EDIT_TITLE  | ``'Edit'``                     | Default title for edit icon of table actions                                                 |
-+-----------------------------+--------------------------------+----------------------------------------------------------------------------------------------+
-| BOOTSTRAP_TABLE_DELETE_TITLE| ``'Delete'``                   | Default title for delete icon of table actions                                               |
-+-----------------------------+--------------------------------+----------------------------------------------------------------------------------------------+
-| BOOTSTRAP_TABLE_NEW_TITLE   | ``'New'``                      | Default title for new icon of table actions                                                  |
-+-----------------------------+--------------------------------+----------------------------------------------------------------------------------------------+
++-----------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------+
+| Configuration Variable      | Default Value                                     | Description                                                                                  |
++=============================+===================================================+==============================================================================================+
+| BOOTSTRAP_SERVE_LOCAL       | ``False``                                         | If set to ``True``, local resources will be used for ``load_*`` methods                      |
++-----------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------+
+| BOOTSTRAP_BTN_STYLE         | ``'primary'``                                     | Default form button style, will change to ``primary`` in next major release                  |
++-----------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------+
+| BOOTSTRAP_BTN_SIZE          | ``'md'``                                          | Default form button size                                                                     |
++-----------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------+
+| BOOTSTRAP_ICON_SIZE         | ``'1em'``                                         | Default icon size                                                                            |
++-----------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------+
+| BOOTSTRAP_ICON_COLOR        | ``None``                                          | Default icon color, follow the context with ``currentColor`` if not set                      |
++-----------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------+
+| BOOTSTRAP_BOOTSWATCH_THEME  | ``None``                                          | Bootswatch theme to use, see available themes at :ref:`bootswatch_theme`                     |
++-----------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------+
+| BOOTSTRAP_MSG_CATEGORY      | ``'primary'``                                     | Default flash message category                                                               |
++-----------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------+
+| BOOTSTRAP_TABLE_VIEW_TITLE  | ``'View'``                                        | Default title for view icon of table actions                                                 |
++-----------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------+
+| BOOTSTRAP_TABLE_EDIT_TITLE  | ``'Edit'``                                        | Default title for edit icon of table actions                                                 |
++-----------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------+
+| BOOTSTRAP_TABLE_DELETE_TITLE| ``'Delete'``                                      | Default title for delete icon of table actions                                               |
++-----------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------+
+| BOOTSTRAP_TABLE_NEW_TITLE   | ``'New'``                                         | Default title for new icon of table actions                                                  |
++-----------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------+
+| BOOTSTRAP_FORM_GROUP_CLASSES| ``'mb-3'``                                        | Default form group classes                                                                   |
++-----------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------+
+|BOOTSTRAP_FORM_INLINE_CLASSES| ``'row row-cols-lg-auto g-3 align-items-center'`` | Default form inline classes                                                                  |
++-----------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------+
 
 .. tip:: See :ref:`button_customization` to learn how to customize form buttons.
diff --git a/docs/macros.rst b/docs/macros.rst
@@ -108,7 +108,13 @@ 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={})
+.. 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
@@ -121,9 +127,13 @@ API
                          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()
 ---------------
 
@@ -154,7 +164,9 @@ API
                     button_map={},\
                     id="",\
                     novalidate=False,\
-                    render_kw={})
+                    render_kw={},\
+                    form_group_classes="",\
+                    form_inline_classes="",)
 
     :param form: The form to output.
     :param action: The URL to receive form data.
@@ -180,6 +192,12 @@ API
     :param novalidate: Flag that decide whether add ``novalidate`` class in ``<form>``.
     :param render_kw: A dictionary, specifying custom attributes for the
                      ``<form>`` tag.
+    :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_inline_classes: Bootstrap 5 only (``bootstrap5/form.html``). You can use this parameter to change the form inline classes,
+                                it will read the config ``BOOTSTRAP_FORM_INLINE_CLASSES`` first (the default value is
+                                ``row row-cols-lg-auto g-3 align-items-center``).
+
 
 .. tip:: See :ref:`button_customization` to learn how to customize form buttons.
 
@@ -239,16 +257,17 @@ API
 ~~~~
 
 .. py:function:: render_form_row(fields,\
-                                 row_class='form-row',\
+                                 row_class='row/form-row',\
                                  col_class_default='col',\
                                  col_map={},\
                                  button_style="",\
                                  button_size="",\
-                                 button_map={})
+                                 button_map={},\
+                                 form_group_classes="")
 
     :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``
-                      or ``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
@@ -260,6 +279,9 @@ API
                         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``)
 
 .. tip:: See :ref:`button_customization` to learn how to customize form buttons.
 

diff --git a/examples/bootstrap4/app.py b/examples/bootstrap4/app.py
@@ -1,12 +1,8 @@
 # -*- coding: utf-8 -*-
-from flask import Flask, render_template, request, flash, Markup
-
+from flask import Flask, render_template, request, flash, Markup, redirect, url_for
 from flask_wtf import FlaskForm, CSRFProtect
-from wtforms import StringField, SubmitField, BooleanField, PasswordField, IntegerField,\
-    FormField, SelectField, FieldList
 from wtforms.validators import DataRequired, Length, Regexp
 from wtforms.fields import *
-
 from flask_bootstrap import Bootstrap4, SwitchField
 from flask_sqlalchemy import SQLAlchemy
 
@@ -126,7 +122,18 @@ def index():
 @app.route('/form', methods=['GET', 'POST'])
 def test_form():
     form = HelloForm()
-    return render_template('form.html', form=form, telephone_form=TelephoneForm(), contact_form=ContactForm(), im_form=IMForm(), button_form=ButtonForm(), example_form=ExampleForm())
+    if form.validate_on_submit():
+        flash('Form validated!')
+        return redirect(url_for('index'))
+    return render_template(
+        'form.html',
+        form=form,
+        telephone_form=TelephoneForm(),
+        contact_form=ContactForm(),
+        im_form=IMForm(),
+        button_form=ButtonForm(),
+        example_form=ExampleForm()
+    )
 
 
 @app.route('/nav', methods=['GET', 'POST'])

diff --git a/examples/bootstrap5/app.py b/examples/bootstrap5/app.py
@@ -1,12 +1,8 @@
 # -*- coding: utf-8 -*-
-from flask import Flask, render_template, request, flash, Markup
-
+from flask import Flask, render_template, request, flash, Markup, redirect, url_for
 from flask_wtf import FlaskForm, CSRFProtect
-from wtforms import StringField, SubmitField, BooleanField, PasswordField, IntegerField,\
-    FormField, SelectField, FieldList
 from wtforms.validators import DataRequired, Length, Regexp
 from wtforms.fields import *
-
 from flask_bootstrap import Bootstrap5, SwitchField
 from flask_sqlalchemy import SQLAlchemy
 
@@ -126,7 +122,18 @@ def index():
 @app.route('/form', methods=['GET', 'POST'])
 def test_form():
     form = HelloForm()
-    return render_template('form.html', form=form, telephone_form=TelephoneForm(), contact_form=ContactForm(), im_form=IMForm(), button_form=ButtonForm(), example_form=ExampleForm())
+    if form.validate_on_submit():
+        flash('Form validated!')
+        return redirect(url_for('index'))
+    return render_template(
+        'form.html',
+        form=form,
+        telephone_form=TelephoneForm(),
+        contact_form=ContactForm(),
+        im_form=IMForm(),
+        button_form=ButtonForm(),
+        example_form=ExampleForm()
+    )
 
 
 @app.route('/nav', methods=['GET', 'POST'])

diff --git a/examples/bootstrap5/templates/form.html b/examples/bootstrap5/templates/form.html
@@ -1,5 +1,5 @@
 {% extends 'base.html' %}
-{% from 'bootstrap4/form.html' import render_form, render_field, render_form_row %}
+{% from 'bootstrap5/form.html' import render_form, render_field, render_form_row %}
 
 {% block content %}
 

diff --git a/flask_bootstrap/__init__.py b/flask_bootstrap/__init__.py
@@ -87,6 +87,11 @@ def init_app(self, app):
         app.config.setdefault('BOOTSTRAP_TABLE_EDIT_TITLE', 'Edit')
         app.config.setdefault('BOOTSTRAP_TABLE_DELETE_TITLE', 'Delete')
         app.config.setdefault('BOOTSTRAP_TABLE_NEW_TITLE', 'New')
+        app.config.setdefault('BOOTSTRAP_FORM_GROUP_CLASSES', 'mb-3')  # Bootstrap 5 only
+        app.config.setdefault(
+            'BOOTSTRAP_FORM_INLINE_CLASSES',
+            'row row-cols-lg-auto g-3 align-items-center'
+        )  # Bootstrap 5 only
 
     def load_css(self, version=None, bootstrap_sri=None):
         """Load Bootstrap's css resources with given version.