WTForms, along with the Flask extension Flask-WTF, provides a powerful and flexible way to integrate forms into a Python web project. These tools are popular in the Flask community for their ease of use and robust features, such as data validation and CSRF protection. However, one limitation is the lack of a built-in mechanism for creating multipage forms in WTForms, where users can navigate through a series of pages — moving both forwards and backwards — within a single form process.
This kind of pagination in WTForms would be incredibly useful in scenarios where you need to gather extensive information without overwhelming the user with a single, long form. By breaking the form into manageable sections, you can improve the user experience and potentially increase completion rates.
In this article, I will guide you through the process of creating a multipage form using WTForms and Flask-WTF. We will explore how to leverage custom attributes and JavaScript to manage page transitions smoothly. This approach allows you to maintain a clean backend while providing a seamless and interactive frontend experience. By the end of this tutorial, you will have a versatile solution that you can easily adapt to any form-based application in your web projects.
How the Pagination in WTForms will Look
If you copy the example code, the pagination will look as follows. The example uses bootstrap but can be adopted for any framework or styling.
Needed Code
main.py
The following main.py script provides a detailed definition of our form, specifying the structure and layout, and determines which fields should appear on each individual page.
from flask_bootstrap import Bootstrap5
from flask import Flask, render_template, redirect
from flask_wtf import FlaskForm, CSRFProtect
from wtforms import StringField
app = Flask(__name__)
app.secret_key = '123456789'
bootstrap = Bootstrap5(app)
csrf = CSRFProtect(app)
# Define Some form
class TestForm(FlaskForm):
test1 = StringField(label="Page1", render_kw={
"uupage": 0 # This sets on which page the field is displayed
})
test2 = StringField(label="Page2", render_kw={
"uupage": 1 # This sets on which page the field is displayed
})
# Include a submit button on the last page
submit = SubmitField(label="Submit", render_kw={
"uupage": 1
})
# add example route for form
@app.route('/test', methods=['GET', 'POST'])
def test():
current_form = TestForm()
max_page = 1 # set to the highest page number
if current_form.validate_on_submit():
# do something with form data
return redirect("https://example.com")
return render_template('index_test.html', form=current_form, max_page=max_page)
if __name__ == '__main__':
app.run(debug=True)
index_test.html
The index_test.html file contains the usual structure for forms, along with some JavaScript code that reads the uupage attributes of each field and, based on those attributes, hides or shows the fields as needed.
{% from 'bootstrap5/form.html' import render_form %}
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>
Test
</title>
{{ bootstrap.load_css() }}
</head>
<body>
<body id="page-top">
<section class="page-section">
<div class="container px-4 px-lg-5">
<h1 class="pt-5 pb-2">Test</h1>
<!-- Actual Form -->
<form method="post" id="order_form">
<div class="mb-3" id="field_container">
{{ render_form(form) }}
</div>
</form>
<!-- Back/Forward Buttons -->
<div id="pagination-controls" class="mb-3">
<button type="button" id="previous-page" class="btn btn-secondary float-end" disabled>Back</button>
<button type="button" id="next-page" class="btn btn-primary">Continue</button>
</div>
</div>
</section>
<!-- Pagination code -->
<script>
document.addEventListener('DOMContentLoaded', function () {
const fields = Array.from(document.querySelectorAll('[uupage]'));
let currentPage = 0;
let max_pages = parseInt("{{ max_page }}", 10);
function showCurrentPage() {
fields.forEach(input => {
const page = input.getAttribute('uupage');
console.log(input, page, currentPage)
if (input.parentElement.id != "field_container") {
if (page == currentPage) {
input.parentElement.style.display = '';
} else {
input.parentElement.style.display = 'none';
}
} else {
if (page == currentPage) {
input.style.display = '';
} else {
input.style.display = 'none';
}
}
});
if (currentPage == max_pages) {
document.getElementById('next-page').style.display = 'none';
document.getElementById('next-page').disabled = true;
} else {
document.getElementById('next-page').style.display = '';
document.getElementById('next-page').disabled = false;
}
if (currentPage != 0) {
document.getElementById('previous-page').style.display = '';
document.getElementById('previous-page').disabled = false;
} else {
document.getElementById('previous-page').style.display = 'none';
document.getElementById('previous-page').disabled = true;
}
}
document.getElementById('previous-page').addEventListener('click', function () {
if (currentPage > 0) {
currentPage--;
showCurrentPage();
}
});
document.getElementById('next-page').addEventListener('click', function () {
if (currentPage < max_pages) {
currentPage++;
showCurrentPage();
}
});
showCurrentPage();
});
</script>
{{ bootstrap.load_js() }}
</body>
</html>requirements.txt
The following versions have been used:
attrs==24.2.0
blinker==1.7.0
Bootstrap-Flask==2.4.0
click==8.1.7
Flask==3.0.3
Flask-WTF==1.2.1
gunicorn==21.2.0
itsdangerous==2.1.2
Jinja2==3.1.3
MarkupSafe==2.1.5
packaging==24.0
referencing==0.35.1
rpds-py==0.20.0
Werkzeug==3.0.2
WTForms==3.1.2Conclusion
In conclusion, while WTForms and Flask-WTF provide excellent tools for form management in Flask applications, their lack of support for multi-page forms requires a bit of creativity. By utilizing custom attributes and JavaScript, we can extend these libraries to create a seamless multi-page form experience. This approach not only enhances the user experience by breaking down complex forms into manageable sections but also retains the robust functionality and security features offered by WTForms and Flask-WTF.
Implementing paged forms can significantly benefit applications that require detailed user input without overwhelming users in a single step. By following the steps outlined in this article, you can easily adapt this solution to fit the specific needs of your web projects, ensuring both functionality and user satisfaction.
Thank you for reading, and I hope this guide helps you enhance your Flask applications with dynamic, user-friendly forms.
Frequently asked questions
Is there a built-in mechanism for pagination in WTForms?
No, there is no built-in mechanism for pagination in flask WTForms and Flask-WTF. That’s why I created the JavaScript described in this article to implement it.
How to implement pagination in a WTForms form?
You can build a custom pagination in flask WTForms or Flask-WTF using JavaScript as described in this article.
What is Flask-WTF?
Flask-WTF is a wrapper for easy implementation of the Python web form builder WTForms inside a Flask Webapp.
What is WTForms?
WTForms is a python framework for creation and validation of web forms such as registration or order forms.
Other interesting articles
- Cloudflare provider v5: Upgrading terraform module-resources
- Travel eSIM from MobiMatter – Experience report
- Bangkok’s New Train Station – My Experiences
M.Sc. in Business Informatics and IT Consultant
I am Pascal, IT developer and consultant from Cologne, specialized in cloud infrastructure and DevOps. In my free time I like to travel, do sports or deal with technology, SmartHome or other nerd topics 🙂
