How to Use Django Widget Tweaks.
When it comes to build forms, Django Forms can be really handy. If your application provide ways for the end-user to input data, it’s strongly advised to do so through the built-in Django Forms. It will automate a good amount of work as well as providing a really stable and secure functionality.
In a nutshell, Django handles three distinct parts of the work involved in forms:
- Preparing and restructuring data to make it ready for rendering;
- Creating HTML forms for the data;
- Receiving and processing submitted forms and data from the client.
The parts 1 and 3 are usually fine for the most cases. But when it comes to the actual HTML forms rendering, sometimes it lacks some options.
That’s where the Django Widget Tweaks takes place. I’ve been using it on my past projects, and I find it really useful. In this brief article, I will introduce you to the basics of this package, and show some of its use cases.
Before we start to talk about the Django Widget Tweaks package itself, I wanted to elaborate a little bit more about the problem I usually face that motivated me to look for this solution.
Most of my projects I use Bootstrap as the base for my css. In some cases I even use it out of the box. If you are familiar with Bootstrap, you probably know it needs some css classes for the forms elements to look good.
A basic example of a form using the Bootstrap classes would be:
The problem usually lives in the need to add some extra attributes to the HTML element, preserving the old ones, that would automatically generated by Django, based on your models. In this case, it would be the div element with
form-group class, as well as the
form-control class in the input element.
For example, if we consider the following model:
And for this model, we create a Django Form:
If we render this form right away, using the following code:
It would look broken, like the picture below:
You can install it with
pip, or download it from PyPI if you prefer:
widget_tweaks to your
I will show just a few of the many options the package offers. You can learn more reading the official docs.
To start using it, you must load the template tag in the template you want to use its functions:
Now expand your form by iterating through its fields, in order to expose the input tags, replacing this:
At this point we already added several Bootstrap elements, but our form still looks broken:
Now to put Django Widget Tweaks in action, add an extra attribute to the
The final result of our template is shown below:
Another way to render the fields is using the
render_field template tag, which gives you a flexible way to render Django fields using a HTML-like syntax:
You can also use the template variables as attribute values:
Personally I find this package really useful, because it let you customize your form elements in a non intrusive way, without having to add extra css class inside the form definition. Also it’s more clear this way, because afterall the css classes are related to the page layout.