Manage Forms

Overview

Currently Aurora only supports WTForms for handling forms.

The WTForms is a third-party package, and you should have it installed on your environment.

If you don't have it yet, install it using the following command:

(venv) pip install WTForms

To see the WTForms documentation please visit the following address:

https://wtforms.readthedocs.io/

Create Form

If you are using WTForms for handling your forms, use the following command to create a new Form Class for an existing app:

(venv) python3 -m manage create-form

It will prompt you for some required arguments.

As an example, here we will create a Form Class called AddNoteForm for our notes app:

(venv) python3 -m manage create-form
App Name: notes
Form Name: AddNoteForm

It will create the mentioned class and updates the _forms.py system module for you.

The Form Name must be in "CamelCase" form with at least two "a-z" and "A-Z" characters.

Even though it's not necessary, but it is a good habit to end your Form Class names with the Form word. Because later you want to import them in your Controllers, and it ensures that name conflicts not happen.

Alternatively you can handle these name conflicts using the import ... as ... syntax.

Let's take a look at the form class created for us:

# Dependencies
from aurora import Forms
from wtforms import *

# The form class
class AddNoteForm(Forms):  
    ...

Now, you need to add some inputs to your form blueprint:

...
class AddNoteForm(Forms):
    title   = StringField(label='Title', validators=[validators.DataRequired()])
    content = TextAreaField(label='Content', validators=[validators.DataRequired()])
    submit  = SubmitField(label='Submit')

Very Important Note:

In Aurora framework by default, the csrf is activated for all your Forms.

But, for whatever reason if you want to inactive it, simply set the csrf property of the Meta class to False. However, I strongly recommend you not to do it.

The csrf token is super important for your application security.

...
# Insecure form class
class InsecureForm(Forms):  
    ...

    class Meta:
        csrf = False

Using Forms

The first step to using Form classes is to import them into your controllers.

As an example, we want to import the created form in our Index controller of our notes app:

# Dependencies
from aurora import Controller, View
from forms.notes import AddNoteForm

# The controller class
class Index(Controller):

    # POST Method
    def post(self):
        pass

    # GET Method
    def get(self):
        form = AddNoteForm()
        return View("index", form=form)

Now we need to add it to the index.html view of the notes app:

{% extends 'notes/layout.html' %}

{% block title %}{% endblock %}

{% block body %}
<h1>Notes App</h1>
<form action="/{{NOTES}}/" method="post" id="add-note-form">
    {{ form.csrf_token }}
    <div>
        {{ form.title.label }}: {{ form.title(class_="input-class") }}
    </div>
    <div>
        {{ form.content.label }}: {{ form.content }}
    </div>
    <div>
        {{ form.submit }}
    </div>
</form>
<div id="result" style="display: none;"></div>
{% endblock %}

The NOTES here is a global variable for your app url.
The form.csrf_token, will creates a hidden input with the name of csrf_token for you.
Using form.title(class_="input-class") syntax, you can add css classes to your inputs.

The above code will generate the following form for you:

<form action="/my-notes/" method="post" id="add-note-form">
    <input id="csrf_token" name="csrf_token" type="hidden" value="...">
    <div>
        <label for="title">Title</label>: 
        <input class="input-class" id="title" name="title" required type="text" value="">
    </div>
    <div>
        <label for="content">Content</label>: 
        <textarea id="content" name="content" required></textarea>
    </div>
    <div>
        <input id="submit" name="submit" type="submit" value="Submit">
    </div>
</form>

You can still design custom forms of your choice, without using this syntax, but remember to add the {{ form.csrf_token }} at the beginning of your form tag.

Now, it's time to validate your form using WTForms validator:

# Dependencies
from aurora import Controller, View
from forms.notes import AddNoteForm
from aurora.security import request

# The controller class
class Index(Controller):

    # POST Method
    def post(self):
        # Form data
        data = request.form

        # Collect form inputs (for later purposes)
        title = data.get('title')
        content = data.get('content')

        # Pass the requested form data to the form class
        form = AddNoteForm(data)

        # Validate the form
        if form.validate():
            return 'Validation passed!'
        else:
            return 'Validation failed!'

    # GET Method
    def get(self):
        form = AddNoteForm()
        return View('index.html', form=form)

Normally you return a rendered template, or a JSON object as the result. Let's send the form with JavaScript and return a JSON response.

Add the following JavaScript Code to the main.js of the notes app statics:

// Document loaded
document.addEventListener('DOMContentLoaded', function() {
    
    // New Task form
    const add_note_form = document.querySelector('#add-note-form');
    if (add_note_form) {
        // Handle form submit
        add_note_form.onsubmit = function () {
            
            // Form date
            const action = this.getAttribute('action');
            const method = this.getAttribute('method');
            const data   = new FormData(this);

            // Submit form data via fetch API
            fetch(action, {
                method: method,
                body:   data,
            })
            .then(response => response.json())
            .then(result => {
                // Result container
                let result_div = document.querySelector('#result');
                
                // Display the result container
                result_div.style.display = 'block';

                // An error occurred
                if (result.error) {
                    result_div.innerHTML = `${result.error}`;
                }

                // Everything is fine
                else if (result.success) {
                    // Show message
                    result_div.innerHTML = `${result.success}`;
                    
                    // Reset the form
                    this.reset();
                }
            });

            // Prevent the form default behavior
            return false
        };
    }
});

Then, update the controller:

...
# The controller class
class Index(Controller):

    # POST Method
    def post(self):
        # Form data
        data = request.form

        # Collect form inputs (for later purposes)
        title = data.get('title')
        content = data.get('content')

        # Pass the requested form data to the form class
        form = AddNoteForm(data)

        # Validate the form
        if form.validate():
            return {
                'success': 'Validation passed!',
            }, 200

        else:
            return {
                'error': 'Validation failed!',
            }, 400
...

Finally, try to submit the form, this time using JavaScript!

Delete Form

You can simply delete an existing form class for an existing app by:

(venv) python3 -m manage delete-form

It prompts you for App Name and Form Name. After confirmation of the data loss, it will delete your form class permanently.