Updated docs and examples about FormData

michalpokusa · michalpokusa · commit 6d7ecd3360db · 2023-06-10T12:36:18.000Z
diff --git a/docs/examples.rst b/docs/examples.rst
@@ -146,6 +146,34 @@ Tested on ESP32-S2 Feather.
     :emphasize-lines: 25-27,39,51,60,66
     :linenos:
 
+Form data parsing
+---------------------
+
+Another way to pass data to the handler function is to use form data.
+Remember that it is only possible to use it with ``POST`` method.
+`More about POST method. <https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST>`_
+
+It is important to use correct ``enctype``, depending on the type of data you want to send.
+
+- ``application/x-www-form-urlencoded`` - For sending simple text data without any special characters including spaces.
+    If you use it, values will be automatically parsed as strings, but special characters will be URL encoded
+    e.g. ``"Hello World! ^-$%"`` will be saved as ``"Hello+World%21+%5E-%24%25"``
+- ``multipart/form-data`` - For sending text and binary files and/or text data with special characters
+    When used, values will **not** be automatically parsed as strings, they will stay as bytes instead.
+    e.g. ``"Hello World! ^-$%"`` will be saved as ``b'Hello World! ^-$%'``, which can be decoded using ``.decode()`` method.
+- ``text/plain`` - For sending text data with special characters.
+    If used, values will be automatically parsed as strings, including special characters, emojis etc.
+    e.g. ``"Hello World! ^-$%"`` will be saved as ``"Hello World! ^-$%"``, this is the **recommended** option.
+
+If you pass multiple values with the same name, they will be saved as a list, that can be accessed using ``request.data.get_list()``.
+Even if there is only one value, it will still get a list, and if there multiple values, but you use ``request.data.get()`` it will
+return only the first one.
+
+.. literalinclude:: ../examples/httpserver_form_data.py
+    :caption: examples/httpserver_form_data.py
+    :emphasize-lines: 32,47,50
+    :linenos:
+
 Chunked response
 ----------------
 
diff --git a/examples/httpserver_form_data.py b/examples/httpserver_form_data.py
@@ -0,0 +1,66 @@
+# SPDX-FileCopyrightText: 2022 Dan Halbert for Adafruit Industries
+#
+# SPDX-License-Identifier: Unlicense
+
+import socketpool
+import wifi
+
+from adafruit_httpserver import Server, Request, Response, GET, POST
+
+
+pool = socketpool.SocketPool(wifi.radio)
+server = Server(pool, debug=True)
+
+
+FORM_HTML_TEMPLATE = """
+<html lang="en">
+    <head>
+        <title>Form with {enctype} enctype</title>
+    </head>
+    <body>
+        <a href="/form?enctype=application/x-www-form-urlencoded">
+            <button>Load <strong>application/x-www-form-urlencoded</strong> form</button>
+        </a><br />
+        <a href="/form?enctype=multipart/form-data">
+            <button>Load <strong>multipart/form-data</strong> form</button>
+        </a><br />
+        <a href="/form?enctype=text/plain">
+            <button>Load <strong>text/plain</strong> form</button>
+        </a><br />
+
+        <h2>Form with {enctype} enctype</h2>
+        <form action="/form" method="post" enctype="{enctype}">
+            <input type="text" name="something" placeholder="Type something...">
+            <input type="submit" value="Submit">
+        </form>
+        {submitted_value}
+    </body>
+</html>
+"""
+
+
+@server.route("/form", [GET, POST])
+def form(request: Request):
+    """
+    Serve a form with the given enctype, and display back the submitted value.
+    """
+    enctype = request.query_params.get("enctype", "text/plain")
+
+    if request.method == POST:
+        posted_value = request.data.get("something")
+
+    return Response(
+        request,
+        FORM_HTML_TEMPLATE.format(
+            enctype=enctype,
+            submitted_value=(
+                f"<h3>Submitted form value: {posted_value}</h3>"
+                if request.method == POST
+                else ""
+            ),
+        ),
+        content_type="text/html",
+    )
+
+
+server.serve_forever(str(wifi.radio.ipv4_address))
diff --git a/examples/httpserver_neopixel.py b/examples/httpserver_neopixel.py
@@ -37,6 +37,9 @@ def change_neopixel_color_handler_post_body(request: Request):
 
     data = request.body  # e.g b"255,0,0"
     r, g, b = data.decode().split(",")  # ["255", "0", "0"]
+    # or
+    data = request.data  # e.g. r=255&g=0&b=0 or r=255\r\nb=0\r\ng=0
+    r, g, b = data.get("r", 0), data.get("g", 0), data.get("b", 0)
 
     pixel.fill((int(r), int(g), int(b)))
 
