Handling Form Submissions

The Client-Server Data Flow

At a high level, the process looks like this:

1. A user fills out a form in their web browser (the "client").
2. They click "Submit," sending the form's data to your Flask application (the "server").
3. Your Flask application receives and processes this data.
4. Your app then sends a response back to the user, perhaps a new page showing the results.

This diagram illustrates the flow:

Step 1: Sending Data with an HTML <form>

The journey begins in your HTML file. To send data, you use the <form> element. Two attributes are critical here:

• method="POST": This tells the browser to send the form data in the body of the request, hidden from the URL. This is the standard and secure way to send data that will modify something or that is sensitive.
• action="/your-target-url": This specifies the URL on your server where the form data should be sent.

Inside the form, you'll have input fields. The name attribute of each <input> is essential. This name becomes the key you'll use in Flask to retrieve the value the user entered.

Let's look at a simple form that asks for a user's name:

<!-- This would be in a file like 'templates/form.html' -->

<form action="/process" method="POST">
    <label for="username">Name:</label>
    
    <!-- The 'name' attribute is 'username'. This is the key we'll use in Flask. -->
    <input type="text" id="username" name="username">
    
    <button type="submit">Submit</button>
</form>

Step 2: Receiving Data in Flask

When the user submits this form, the browser sends a POST request to the /process URL on your server. Your Flask application needs to be ready to catch it.

To do this, we use the global request object from Flask. This object contains all the information about the incoming request from the browser.

• request.method: This tells you if the request was a GET or a POST. We can use this to show the form on a GET request and process the data on a POST request.
• request.form: This is a special dictionary-like object that holds all the data from a submitted form. You can access the data using the name attributes from your HTML inputs as keys.

For example, to get the data from the form above, you would use:
user_input_name = request.form['username']

Now, let's see this whole process in action.

A Complete Example

The following video from Tech With Tim provides a clear, step-by-step walkthrough of creating a form and handling the submitted data in Flask. It covers everything we just discussed.

For a textual reference that you can follow along with, this article from DigitalOcean is excellent. It covers the same concepts with clear code examples.

Let's consolidate what you've learned into a single, clean example.

Assume you have this project structure:

my-ai-app/
|-- app.py
|-- templates/
    |-- form.html
    |-- result.html

1. templates/form.html
This file contains the form for the user to fill out. When the user visits /data-entry, this is what they will see.

<!DOCTYPE html>
<html>
<head>
    <title>Enter Data</title>
</head>
<body>
    <h1>What text do you want to analyze?</h1>
    <form action="/data-entry" method="POST">
        <textarea name="user_text" rows="4" cols="50"></textarea>
        <br>
        <button type="submit">Submit Text</button>
    </form>
</body>
</html>

Notice we're using a <textarea> which is better for long text, but it works the same way with a name attribute.

2. templates/result.html
This page will display the text that the user submitted.

<!DOCTYPE html>
<html>
<head>
    <title>Submitted Data</title>
</head>
<body>
    <h1>You submitted the following text:</h1>
    <p style="border: 1px solid #ccc; padding: 10px; background-color: #f9f9f9;">
        {{ submitted_text }}
    </p>
    <a href="/data-entry">Submit another text</a>
</body>
</html>

3. app.py
This is where the magic happens. The /data-entry route now handles two scenarios.

from flask import Flask, render_template, request

app = Flask(__name__)

@app.route('/data-entry', methods=['GET', 'POST'])
def data_entry():
    # Check if the request is a POST request (i.e., the form was submitted)
    if request.method == 'POST':
        # Get the text from the textarea, which has name="user_text"
        text = request.form['user_text']
        
        # Now, render the result page, passing the submitted text to it
        return render_template('result.html', submitted_text=text)

    # If it's a GET request, just show the form page
    return render_template('form.html')

if __name__ == '__main__':
    app.run(debug=True)

Run this app.py file and navigate to http://127.0.0.1:5000/data-entry. You'll see the form. Type something in the box and click submit. You will be taken to the result page, which displays the text you entered!

<!DOCTYPE html>
<html>
<head>
    <title>Enter Data</title>
</head>
<body>
    <h1>Mad Libs!</h1>
    <form action="/data-entry" method="POST">
        <label for="noun">Noun:</label><br>
        <input type="text" id="noun" name="noun"><br><br>
        
        <label for="verb">Verb (ending in 'ing'):</label><br>
        <input type="text" id="verb" name="verb"><br><br>
        
        <label for="user_text">Adjective:</label><br>
        <input type="text" id="user_text" name="user_text"><br><br>

        <button type="submit">Create Story</button>
    </form>
</body>
</html>

from flask import Flask, render_template, request

app = Flask(__name__)

@app.route('/data-entry', methods=['GET', 'POST'])
def data_entry():
    if request.method == 'POST':
        # Get all three values from the form
        noun = request.form['noun']
        verb = request.form['verb']
        adjective = request.form['user_text']
        
        return render_template('result.html', noun=noun, verb=verb, adjective=adjective)

    return render_template('form.html')

if __name__ == '__main__':
    app.run(debug=True)

<!DOCTYPE html>
<html>
<head>
    <title>Your Story</title>
</head>
<body>
    <h1>Your silly story:</h1>
    <p>
        The <strong>{{ adjective }}</strong> <strong>{{ noun }}</strong> was busy <strong>{{ verb }}</strong> by the river.
    </p>
    <a href="/data-entry">Play again</a>
</body>
</html>

Conclusion

Excellent work! You now understand the complete round-trip of data in a web application: sending data from a client's browser and receiving it on your server. This is a fundamental skill for any web developer.

Key Takeaways:

• HTML <form>s with method="POST" are used to send data to the server.
• The name attribute of an <input> or <textarea> is the key for accessing its data.
• In Flask, a route must specify methods=['GET', 'POST'] to handle form submissions.
• You can check if request.method == 'POST' to run specific logic for submitted forms.
• The form data is available in the request.form dictionary-like object.

In the next lesson, we will refine this process. Instead of having the server send back a whole new HTML page, we will create an API endpoint. This is a special URL that returns just raw data (in a format called JSON), not a full webpage. This technique is what allows modern web apps to feel fast and interactive, updating parts of a page without a full reload. It's the final piece we need before we can connect your user interface to the Gemini AI.