Decode a URL parameter string into a map.
<p:declare-step type="p:www-form-urldecode"> <output port="result" primary="true" content-types="application/json" sequence="true"/> <option name="value" as="xs:string" required="true"/> </p:declare-step>
The p:www-form-urldecode
step decodes a URL parameter string (like a=b&c=d
) into a map. The result appears on the result
port as a JSON document.
Ports:
Port | Type | Primary? | Content types | Seq? | Description |
---|---|---|---|---|---|
|
|
|
|
| The resulting map, as a JSON document. |
Options:
The p:www-form-urldecode
step is one of the few steps that have no primary input port, its main input is the value of the value
option. This value must be a valid URL 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 p:www-form-urldecode
step takes such a string in its value
option and converts it into a map. Each name/value pair in the input
string is represented as a key/value pair in the map. Percent encoded values (like %20
for space) are decoded. The +
sign also acts as a space.
The resulting map appears on the result
port as a JSON document.
There is also a step for encoding these kinds of strings, called p:www-form-urlencode
.
Pipeline document:
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0"> <p:output port="result"/> <p:www-form-urldecode value="a=b&b=a%20b&c=d+e+f"/> </p:declare-step>
Result document:
{"a":"b","b":"a b","c":"d e f"}
Now assume you’re interested in parameter c
and want to turn its value into an XML element. This is how you can do
this:
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0"> <p:output port="result"/> <p:www-form-urldecode value="a=b&b=a%20b&c=d+e+f"/> <p:identity> <p:with-input> <result-c>{.?c}</result-c> </p:with-input> </p:identity> </p:declare-step>
Result document:
<result-c>d e f</result-c>
The document coming out of the p:www-form-urldecode
step is a map. This map flows through my pipeline. The p:identity
step, since it
directly follows p:www-form-urldecode
, can address this map with the dot .
operator. And .?c
is syntactic sugar for: give me the
value of the context item map with the key 'c'
. You could also have written it as .('c')
.
When the string to decode contains multiple parameters with the same name, the result for that key will be a sequence of values. We cannot serialize such a result directly (since JSON doesn't allow map entries with multiple values), but we can access and work with it in our program.
In the following example, parameter a
is duplicated. The p:identity
step combines the values for
a
with a pipe character |
, using the XPath string-join()
function.
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0"> <p:output port="result"/> <p:www-form-urldecode value="a=b&b=a%20b&a=d+e+f"/> <p:identity> <p:with-input> <result-a-sequence>{string-join(.?a, '|')}</result-a-sequence> </p:with-input> </p:identity> </p:declare-step>
Result document:
<result-a-sequence>b|d e f</result-a-sequence>
The document appearing on the result
port only has a content-type
property. It has no other
document-properties (also no base-uri
).
If any parameter name occurs more than once in the input string, a sequence will be associated with the respective key. The order in the sequence retains the order of name/value pairs in the encoded string. However, if this happens, you cannot serialize (write to, for instance, disk) the result because it is no longer valid JSON. You can however still use the map in your program and access its members. See also the Parameters with the same name example
Error code | Description |
---|---|
It is a dynamic error if the |
This description of the p:www-form-urldecode
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-urldecode
step can be found here.
The p:www-form-urldecode
step is part of categories:
The p:www-form-urldecode
step is also present in version:
3.1.