p:www-form-urlencode (3.1)

Encode parameters into a URL string.

Summary
Description
Examples
- Basic usage
- Multiple parameter values
Additional details
Reference information

Summary

<p:declare-step type="p:www-form-urlencode">
  <output port="result" primary="true" content-types="text/plain" sequence="true"/>
  <option name="parameters" as="map(xs:string,xs:anyAtomicType+)" required="true"/>
</p:declare-step>

The p:www-form-urlencode step encodes a set of parameters, given as entries in a map, into a URL parameter string (like a=b&c=d). The result appears on the result port as a text document.

Ports:

Type	Port	Primary?	Content types	Seq?	Description
`output`	`result`	`true`	`text/plain`	`true`	The resulting URL parameter string, as a text document.

Options:

Name	Type	Req?	Description
`parameters`	`map(xs:string,xs:anyAtomicType+)`	`true`	A map with the parameters to encode.

Description

The p:www-form-urlencode step is one of the few steps that have no primary input port, its main input is the value of the parameters option. This value must be a map. The keys in the map are the parameter names, the value(s) the parameter values. The result will be a parameter string (the part that usually comes after the ? in a URL, like a=b&c=d). Officially, this is called a x-www-form-urlencoded string. This format is also used for sending HTML form data over HTTP.

The resulting parameter string appears on the result port as a text document.

There is also a step for decoding these kinds of strings, called p:www-form-urldecode.

Examples

Basic usage

Pipeline document:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">
  
  <p:output port="result"/>

  <p:www-form-urlencode parameters="map{ 'a': 'b', 'c': 'd e f' }"/>

</p:declare-step>

Result document:

a=b&c=d+e+f

Multiple parameter values

If an entry in the map has multiple values (here for the entry with key a), the parameter is repeated in the output:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">
  
  <p:output port="result"/>

  <p:www-form-urlencode parameters="map{ 'a': ('b', 'b2'), 'c': 'd e f' }"/>

</p:declare-step>

Result document:

a=b&a=b2&c=d+e+f

Additional details

The document appearing on the result port only has a content-type property. It has no other document-properties (also no base-uri).
If an entry in the map has multiple values, an entry for each value will appear in the resulting URL string. See also the Multiple parameter values example.

Reference information

This description of the p:www-form-urlencode step is for XProc version: 3.1. This is a required step (an XProc 3.1 processor must support this).

The formal specification for the p:www-form-urlencode step can be found here.

The p:www-form-urlencode step is part of categories:

The p:www-form-urlencode step is also present in version: 3.0.