Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/LaunchPlatform/wtforms-bootstrap5
Simple library for rendering WTForms in HTML as Bootstrap 5 form controls
https://github.com/LaunchPlatform/wtforms-bootstrap5
forms jinja2 python template wtforms
Last synced: about 2 months ago
JSON representation
Simple library for rendering WTForms in HTML as Bootstrap 5 form controls
- Host: GitHub
- URL: https://github.com/LaunchPlatform/wtforms-bootstrap5
- Owner: LaunchPlatform
- License: mit
- Created: 2022-06-16T20:04:03.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2023-09-15T00:52:07.000Z (over 1 year ago)
- Last Synced: 2024-11-19T09:57:10.362Z (2 months ago)
- Topics: forms, jinja2, python, template, wtforms
- Language: Python
- Homepage:
- Size: 123 KB
- Stars: 21
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- jimsghstars - LaunchPlatform/wtforms-bootstrap5 - Simple library for rendering WTForms in HTML as Bootstrap 5 form controls (Python)
README
# WTForms-Bootstrap5
Simple library for rendering WTForms in HTML as Bootstrap 5 form controls
**Notice: this project is still in very early stage, the API may change a lots rapidly**
## Features
- **MIT licensed** - it doesn't infect your code
- **Light weight** - not much code and little dependencies
- **Latest Bootstrap 5** - generates forms in latest Bootstrap 5 style
- **Highly customizable** - you can generate different kind of Bootstrap 5 form controls and layouts
- **Template engine friendly** - chained method calls making it easy to integrate with template engine
- **Covered with automatic tests** - yep, we have test cases
## Why?
Everytime I build a website with [WTForms](https://wtforms.readthedocs.io), I spend way too much time in writing HTML and [Jinja template](https://jinja.palletsprojects.com/) for rendering a form as [Bootstrap 5 form controls](https://getbootstrap.com/docs/5.2/forms/overview/).
Work smart is an important value we have here at [Launch Platform](https://launchplatform.com), so I wonder why not make a library for making rendering Bootstrap 5 style WTForms controls easily?
So here you go, wtforms-bootstrap5 is created, open sourced under MIT license.
It's a simple Python library for rendering WTForms in Bootstrap 5 favor.
## Install
To install the formatter, simply run
```bash
pip install wtforms-bootstrap5
```
## Example
First, you define your form as you would usually do with WTForms:
```python
from wtforms import Form
from wtforms import EmailField
from wtforms import PasswordField
from wtforms import SelectField
from wtforms import BooleanField
from wtforms import SubmitField
class MyForm(Form):
email = EmailField("Email", render_kw=dict(placeholder="Foobar"))
password = PasswordField("Password", description="Your super secret password")
city = SelectField("City", choices=["Los Angle", "San Francisco", "New York"])
agree_terms = BooleanField("I agrees to terms and service")
submit = SubmitField()
```
Then you can use `RenderContext` for rendering your form like this
```python
from wtforms_bootstrap5 import RendererContext
form = MyForm()
context = RendererContext()
html = context.render(form)
```
The form will be rendered as HTML like
```html
Email
PasswordYour super secret password
CityLos AngleSan FranciscoNew York
I agrees to terms and service
```
And it will look like this
By default, a sensible simple layout style will be used.
## Customize the form
There are many similar open source libraries out there, but most of them are very hard to customize.
Once you adopt it, then you can only render your form in a specific style.
As a result, I found myself writing HTML manually without using the library to save time.
To avoid the same mistake, we want to make wtforms-bootstrap5 very easy to customize without compromising too much of its reusability.
Here's an example how you can turn the example above into a column based form.
```python
html = (
renderer_context
.form(action="/sign-up")
.default_field(
row_class="row mb-3",
label_class="form-label col-2",
field_wrapper_class="col-10",
field_wrapper_enabled=True,
)
.field(
"agree_terms",
wrapper_class="offset-2",
wrapper_enabled=True,
field_wrapper_enabled=False,
)
.field(
"submit",
field_wrapper_class="offset-2",
field_wrapper_enabled=True,
)
).render(form)
```
And this is how it looks like
As you can see in the example, we use `default_field` method for overwriting the options of all fields by default.
We also use `field` method for overwriting the options for a specific field.
The `field` method takes multiple input name arguments, so that you can overwrite options for multiple fields at once like this
```python
html = (context
.field("email", "password", label_class="my-custom-class", ...)
)
```
Please notice that, **the order of `default_field` and `field` method calls matter**.
When `field` is called, the current default field options will be used as the default values.
So if you make the calls in order like this
```python
html = (context
.field("email", row_class="row")
.default_field(label_class="my-custom-class")
)
```
The `label_class` for `email` field here will be `form-label` instead of `my-custom-class` since when it's called, the original default value was still `form-label`.
To customize the form element, you can use the `form` method like this
```python
html = (context
.form(
method="POST",
action="/sign-up",
enctype="application/x-www-form-urlencoded",
form_class="my-form",
form_attrs=dict(custom="value")
)
)
```
### Add submit button or other fields
Sometimes, define a submit button for each form is not desirable.
Or, the form could be automatically generated and doesn't come with a submit button.
In those cases, you can use `add_field` to add any extra fields into the end of the form.
Like this:
```python
html = (
renderer_context
.add_field("submit", SubmitField())
.field(
"submit",
field_wrapper_class="offset-2",
field_wrapper_enabled=True,
)
).render(form)
```
Since adding a submit button is very common, so you can also use `add_submit` instead if the field to add is a `SubmitField`.
The default submit field name is `submit`, so you don't need to provide it if you want to make it `submit`.
Arguments of `SubmitField` can be passed in, such as `label`.
```python
html = (
renderer_context
.add_submit(label="Update")
.field(
"submit",
field_wrapper_class="offset-2",
field_wrapper_enabled=True,
)
).render(form)
```
As you can see in the example, the decorate options also work for the newly added submit field.
If you want to change the default submit field class, you can pass in `submit_field_cls` argument when creating the context like this.
```python
html = (
RenderContext(submit_field_cls=SubmitButton)
.add_submit()
).render(form)
```
### Field HTML structure
In general, the field HTML structure can be controlled by the option values and it looks like this
```html
Email
Your super secret password
Bad password
```
## Integrate with template engine
We want to make it as easy as possible to integrate with template engine such as [Jinja](https://jinja.palletsprojects.com/).
That's why we use chained method calls for customizing the form.
You should be able to pass the `form` and `RenderContext` objects and write all your form customization from the template.
This way, you don't get your view relative code pollute your controller code.
For example, after passing `form` and `render_context` object, you can write this in Jinja:
```html
New user
{{
renderer_context
.default_field(
row_class="row mb-3",
label_class="form-label col-2",
field_wrapper_class="col-10",
field_wrapper_enabled=True,
)
.field(
"agree_terms",
wrapper_class="offset-2",
wrapper_enabled=True,
field_wrapper_enabled=False,
)
.field(
"submit",
field_wrapper_class="offset-2",
field_wrapper_enabled=True,
)
).render(form)
}}
```
## Feedbacks
Feedbacks, bugs reporting or feature requests are welcome 🙌, just please open an issue.
No guarantee we have time to deal with them, but will see what we can do.