# Django Forms

This page explains how to **manage and validate a form in Django** Framework. We assume the audience has already a Django project up and running. For those that start from nothing, feel free to access the resources mentioned below and come back here once the content is understood:

* 👉 [How to install Django](/docs/content/tutorials/django-how-to-install.md) - simple, tested steps to install Django
* 👉 [Django for beginners](/docs/content/tutorials/django-for-beginners.md) - a comprehensive tutorial that covers the basics

> Topics covered by this tutorial

* ✅ Create a new Django app
* ✅ Define a new route
* ✅ Update the configuration to include the new application
* ✅ Code a simple form 
* ✅ Integrate the Form into a real page
* ✅ Update the controller to check the form is validated

The video presentation of this tutorial can be found on Github:

{% embed url="<https://www.youtube.com/watch?v=te350w1WwfQ>" %}
Django For Beginners - How to add a new form
{% endembed %}

## Create a new Application

> For this, we will use the `startapp` Django subcommand:

```bash
$ python manage.py startapp forms
```

> Add a simple view in forms - `forms/views.py`

```python
# File contents: forms/views.py

from django.shortcuts import render

from django.http import HttpResponse 

def index(request):                                  
    return HttpResponse("Hello Django - Forms")
```

> Define the routing for our new app - `forms/urls.py`

```python
from django.urls import path, re_path
from forms import views

urlpatterns = [

    # The home page
    path('forms/', views.index, name='home'),
]
```

> Update settings to include the new app - `config/settings.py`

```python
# File: config/settings.py (partial content)
...
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'forms',                           # <-- NEW
]
```

> Update routing - `config/urls.py`

```python
from django.contrib import admin
from django.urls import path, include  # <-- UPDATED to add 'include'    

urlpatterns = [
    path('admin/', admin.site.urls),
    path(""      , include("forms.urls")), # Forms app routing
]
```

Once we restart the project, the new route `/forms` should be visible:

![Django Forms -  A Hello-World type route](/files/-Mcc_Xb0SjKp4RN18B4V)

<br>

## Define a new form

Inside the newly created app, we need to create a `forms` file and define the new Form Class object.

```python
# File contents: forms/forms.py

from django import forms 
 
class HelloForm(forms.Form): 

    title   = forms.CharField() 
    message = forms.CharField() 
    email   = forms.EmailField(required=False) 
```

<br>

> Controller code - `forms/views.py`, the `index()` method

```python
from .forms import HelloForm

def index(request):                   
       
    if request.method == 'POST': 
        form = HelloForm(request.POST) 
        if form.is_valid(): 
            return HttpResponse("Form is valid")
            
    else: 
        form = HelloForm() 

    return render(request, 'hello.html', {'form': form}) 
```

<br>

> Update App configuration to include the new `Templates` folder, `core/settings.py` for AppSeed projects.

```python
FORMS_TEMPLATES = os.path.join(CORE_DIR, "forms/templates") # <-- NEW 

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [TEMPLATE_DIR, FORMS_TEMPLATES],            # <-- UPDATED LINE  
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
                'apps.context_processors.cfg_assets_root',
            ],
        },
    },
] 
```

<br>

> HTML page - defined in `forms/templates` folder:

```markup
<form action="" method="post"> 
    {\% csrf_token \%} <!-- NOTE: remove the Back Slash character -->

    <table> 
        {{ form.as_table }} 
    </table>      
    <br />
    <input type="submit" value="Submit"> 
</form> 
```

![Django Forms - Completed with user Data](/files/-Mcci1ek4mCT5IzHdygQ)

If all fields are provided, on submit, we should see the `Form is valid` message.

<br>

> Update the form with a new field `ID` (numeric type):

```python
from django import forms 
 
class HelloForm(forms.Form): 

    title   = forms.CharField()
    message = forms.CharField() 
    id      = forms.IntegerField()              # <-- NEW form field  
    email   = forms.EmailField(required=False) 
```

> The page server to the users is updated automaticaly to include the new field

![Django Forms - Integer Field Added](/files/-Mcck12lqQaax3R91ee6)

> Thanks for reading! For more topics, feel free to [contact](https://appseed.us/support) Appseed.

## Resources

* Read more about [Django](https://www.djangoproject.com/) (official docs)
* Start fast a new project using *development-ready* [Django Starters](https://appseed.us/admin-dashboards/django)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://appseed.gitbook.io/docs/content/tutorials/django-forms.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.