Forms

GTForm is the foundation of form management in Django Gentelella Widgets. It provides Bootstrap-compatible rendering methods and integrates seamlessly with the widget library.

Basic Usage

Inherit from GTForm instead of forms.Form:

from django import forms
from djgentelella.forms.forms import GTForm
from djgentelella.widgets import core as genwidgets

class ContactForm(GTForm, forms.Form):
    name = forms.CharField(widget=genwidgets.TextInput)
    email = forms.EmailField(widget=genwidgets.EmailInput)
    message = forms.CharField(widget=genwidgets.Textarea)

With ModelForm

GTForm can be combined with ModelForm:

from django import forms
from djgentelella.forms.forms import GTForm
from djgentelella.widgets import core as genwidgets

class PersonForm(GTForm, forms.ModelForm):
    class Meta:
        model = Person
        fields = ['name', 'email', 'birth_date', 'country']
        widgets = {
            'name': genwidgets.TextInput,
            'email': genwidgets.EmailInput,
            'birth_date': genwidgets.DateInput,
            'country': genwidgets.Select,
        }

Render Methods

GTForm provides multiple rendering methods for Bootstrap layouts:

as_horizontal (default)

Labels and inputs side by side in a horizontal layout. This is the default render type.

{{ form.as_horizontal }}

as_inline

Labels appear inline with form fields.

{{ form.as_inline }}

as_plain

Simple stacked layout with labels above inputs.

{{ form.as_plain }}

as_grid

Custom grid layout allowing you to arrange fields in rows and columns.

{{ form.as_grid }}

Specifying Render Type

You can set the render type when creating the form instance:

# In your view
form = ContactForm(render_type='as_inline')

Or set a default for the form class:

class ContactForm(GTForm, forms.Form):
    default_render_type = 'as_plain'

    name = forms.CharField(widget=genwidgets.TextInput)
    email = forms.EmailField(widget=genwidgets.EmailInput)

Grid Layout

The as_grid method allows custom field arrangement. Define the layout using grid_representation:

from django import forms
from djgentelella.forms.forms import GTForm
from djgentelella.widgets import core as genwidgets

class AddressForm(GTForm, forms.Form):
    # Define the grid layout: rows of columns of fields
    grid_representation = [
        # Row 1: Two columns with one field each
        [['first_name'], ['last_name']],
        # Row 2: Full width field
        [['address']],
        # Row 3: Three columns
        [['city'], ['state'], ['zip_code']],
        # Row 4: Two columns
        [['country'], ['phone']],
    ]

    first_name = forms.CharField(widget=genwidgets.TextInput)
    last_name = forms.CharField(widget=genwidgets.TextInput)
    address = forms.CharField(widget=genwidgets.TextInput)
    city = forms.CharField(widget=genwidgets.TextInput)
    state = forms.CharField(widget=genwidgets.TextInput)
    zip_code = forms.CharField(widget=genwidgets.TextInput)
    country = forms.ChoiceField(widget=genwidgets.Select, choices=[])
    phone = forms.CharField(widget=genwidgets.PhoneNumberMaskInput)

In your template:

{{ form.as_grid }}

The grid structure is:

grid_representation = [
    [['field1'], ['field2']],  # Row with 2 columns
    [['field3']],               # Row with 1 column (full width)
    [['field4'], ['field5'], ['field6']],  # Row with 3 columns
]

Each row is automatically sized based on the number of columns (Bootstrap grid system).

Template Usage

In your template, render the form using any method:

{% extends 'gentelella/base.html' %}

{% block content %}
<form method="post" enctype="multipart/form-data">
    {% csrf_token %}

    {# Choose one render method: #}
    {{ form.as_horizontal }}
    {# or {{ form.as_inline }} #}
    {# or {{ form.as_plain }} #}
    {# or {{ form.as_grid }} #}

    <button type="submit" class="btn btn-primary">Submit</button>
</form>
{% endblock %}

FormSets

Use GTFormSet for managing multiple forms:

from django.forms import formset_factory
from djgentelella.forms.forms import GTForm, GTFormSet
from djgentelella.widgets import core as genwidgets

class ItemForm(GTForm, forms.Form):
    name = forms.CharField(widget=genwidgets.TextInput)
    quantity = forms.IntegerField(widget=genwidgets.NumberInput)
    price = forms.DecimalField(widget=genwidgets.FloatInput)

ItemFormSet = formset_factory(ItemForm, formset=GTFormSet, extra=3)

In your view:

def items_view(request):
    if request.method == 'POST':
        formset = ItemFormSet(request.POST)
        if formset.is_valid():
            for form in formset:
                # Process each form
                pass
    else:
        formset = ItemFormSet()
    return render(request, 'items.html', {'formset': formset})

In your template:

<form method="post">
    {% csrf_token %}
    {{ formset.as_horizontal }}
    <button type="submit">Save</button>
</form>

Model FormSets

Use GTBaseModelFormSet for model-based formsets:

from django.forms import modelformset_factory
from djgentelella.forms.forms import GTForm, GTBaseModelFormSet
from djgentelella.widgets import core as genwidgets

class ProductForm(GTForm, forms.ModelForm):
    class Meta:
        model = Product
        fields = ['name', 'price', 'stock']
        widgets = {
            'name': genwidgets.TextInput,
            'price': genwidgets.FloatInput,
            'stock': genwidgets.NumberInput,
        }

ProductFormSet = modelformset_factory(
    Product,
    form=ProductForm,
    formset=GTBaseModelFormSet,
    extra=1,
    can_delete=True
)

Complete Example

Here’s a comprehensive example combining multiple features:

from django import forms
from djgentelella.forms.forms import GTForm
from djgentelella.widgets import core as genwidgets
from djgentelella.widgets.selects import AutocompleteSelect

class OrderForm(GTForm, forms.ModelForm):
    # Custom grid layout
    grid_representation = [
        [['customer'], ['order_date']],
        [['shipping_address']],
        [['city'], ['state'], ['postal_code']],
        [['notes']],
    ]

    class Meta:
        model = Order
        fields = [
            'customer', 'order_date', 'shipping_address',
            'city', 'state', 'postal_code', 'notes'
        ]
        widgets = {
            'customer': AutocompleteSelect('customerbasename'),
            'order_date': genwidgets.DateInput,
            'shipping_address': genwidgets.TextInput,
            'city': genwidgets.TextInput,
            'state': genwidgets.Select,
            'postal_code': genwidgets.TextInput,
            'notes': genwidgets.Textarea,
        }

In your view:

def create_order(request):
    if request.method == 'POST':
        form = OrderForm(request.POST, render_type='as_grid')
        if form.is_valid():
            form.save()
            return redirect('order_list')
    else:
        form = OrderForm(render_type='as_grid')
    return render(request, 'order_form.html', {'form': form})

API Reference

class djgentelella.forms.forms.GTBaseModelFormSet(data=None, files=None, auto_id='id_%s', prefix=None, queryset=None, *, initial=None, **kwargs)

add_fields(form, index)

Add a hidden field for the object’s primary key.

ordering_widget

alias of HiddenInput

class djgentelella.forms.forms.GTForm(*args, **kwargs)

GTForm is the basis of form management, it does the work of django forms.Form, including enhancements and boostrap rendering, so it should be inherited from this form, rather than forms.Form.

Example of use:

from djgentelella.forms.forms import GTForm
class MyForm(GTForm):
     myfield = forms.TextField()

Using with forms.ModelForm

from djgentelella.forms.forms import GTForm
class MyForm(GTForm, forms.ModelForm):
     myfield = forms.TextField()
     class Meta:
       model = MyModel

Creating an instance and specify how render it.

myform = myGTForm(render_type='as_inline', ... )

as_grid()

Allow you to arrange the form fields in rows and cols, When you use this render needs to fill grid_representation attribute in your form Return this form rendered as HTML using grid bootstrap approach.,

grid_representation=[
    [ ['key'],[], [] ],
    [ [], [] ],
]

as_horizontal()

Return this form rendered as HTML using as_horizontal bootstrap approach.

as_inline()

Return this form rendered as HTML using as_inline bootstrap approach.

as_plain()

Returns this form rendered as HTML using as_plain bootstrap approach.

property grid

Example of return structure:

[
    [ [forms.Field],[], [] ],
    [ [], [] ],
]

property media

Return all media required to render the widgets on this form.

class djgentelella.forms.forms.GTFormSet(data=None, files=None, auto_id='id_%s', prefix=None, initial=None, error_class=<class 'django.forms.utils.ErrorList'>, form_kwargs=None, error_messages=None)

This class Allow to manage FormSet using GTForm and Widgets, provide an implementation to integrate with django formset system.

add_fields(form, index)

A hook for adding extra fields on to each form instance.

ordering_widget

alias of HiddenInput