Encode parameters into a URL string.
<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:
Port | Type | Primary? | Content types | Seq? | Description |
---|---|---|---|---|---|
|
|
|
|
| The resulting URL parameter string, as a text document. |
Options:
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
.
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
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
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.
This description of the p:www-form-urlencode
step is for XProc version: 3.0. This is a required step (an XProc 3.0 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.1.