Splitting simple form data into key/value pairs

WWW Form Data

Preliminaries

This note describes how and when the server processes request bodies that are encoded as type application/x-www-form-urlencoded

When an HTML form is submitted by a browser, the values of the form fields are passed to the sever in the request body.

The server's form data handler is responsible for parsing the request body into key/value pairs.

When successful, each form field is added to the server's _formDataMap. The HTML element's "name" attribute is used as a key within this map. The user's value is stored as the target of that key.

HTML sample

Consider an HTML page with this form:

<html>
    <form method=POST action='/api/save-form-data' enctype='x-www-form-urlencoded'>
        <input type=text name='accountNumber' value='ES-ABC-DEFGH'>
        <input type=text name='accountName' value='José María Álvarez'>
        <input type=text name='country' value='ES'>
        <input type=submit Submit>
    </form>
</html>

Router

The server could be configured to route incoming POSTs to a custom plugin to handle the saving of this data. The server config might look like this:

server {
    plugins {
        my-custom-handler {
            location `/srv/www.example.com/plugins/my-custom-handler/index.js`
          }
        router {
            `/api/*`  *methods=POST  *plugin=my-custom-handler
        }
    }
}

Server parsing

When the server receives the user's submittal, its built-in form-data-handler will examine the content-type to see if it is application/x-www-form-urlencoded. If it is, the server will parse the contents of the request body, which might look like this:

accountNumber=ES-ABC-DEFGH&accountName=Jos%C3%A9%20Mar%C3%ADa%20%C3%81lvarez&country=ES

The parser will split this payload into three parts, using the ampersand as the separator:

accountNumber=AN-ABC-DEFGH
accountName=Jos%C3%A9%20Mar%C3%ADa%20%C3%81lvarez
country=ES

Each part will be split into a key and a value, using the equals-sign as the separator, and values that are URI encoded will be properly decoded as UTF-8:

key	value
accountNumber	AN-ABC-DEFGH
accountName	José María Álvarez
country	ES

Work order

Each of the three key/value pairs will be added to the workOrder's _formDataMap. The custom handler plugin can access them like this:

class MyCustomHandler {
    async processingSequence(workOrder) {
    
        if (workOrder.hasFormData('accountNumber')
            var acctNum = workOrder.getFormData('accountNumber'); 
        
        if (workOrder.hasFormData('accountName')
            var acctName = workOrder.getFormData('accountName'); 
        
        if (workOrder.hasFormData('accountName')
            var isoCode = workOrder.getFormData('accountName'); 
    }
}

Configuration

There are no configurable options associated with this handler.

Review

Key points to remember:

The form-data handler is automatically invoked for POST requests when the content-type is application/x-www-form-urlencoded.
The parsed data is available to plugins via the WorkOrder's _formDataMap object, the hasFormData method and the getFormData method.