Splitting simple form data into key/value pairs

WWW Form Data


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:

<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>


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:


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');


There are no configurable options associated with this handler.


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.

Splitting simple form data into key/value pairs

🔗 🔎