Previous Up Next


p:www-form-urldecode

p:www-form-urldecode — Decodes URL encoded form data.

Synopsis

<p:declare-step type="p:www-form-urldecode">
     <p:output port="result"/>
     <p:option name="value" required="true"/>                      <!-- string -->
</p:declare-step>

Description

The most common way for browsers to send parameters to a web service is with an encoding called “x-www-form-urlencoded”. You've all seen it:

  1 http://example.org/service?a=b&c=d&e=&f

The “a=b&c=d&e=&f” part is the three parameters (a=b, c=d, and e=f) sent in x-www-form-urlencoded format.

The p:www-form-urldecode step interprets a URL encoded string and returns a c:param-set containing the parameters. This step is the effectively the opposite of p:www-form-urlencode.

The order of the c:param elements in the result is the same as the order of the encoded parameters, reading from left to right.

If any parameter name occurs more than once in the encoded string, the resulting parameter set will contain a c:param for each instance. However, only one of these will actually be used if the parameter set is passed to another step on its parameter input port.

One limitation of this step is that it cannot represent a set of parameters if the names are not ordinary XML “local names”. Attempting to decode the following string, for example, will cause the step to fail:

  1 x::y=value

The name “x::y” cannot be represented in a c:param-set.

Errors

Error Description
err:C0037 Occurs if the value provided is not a properly x-www-form-urlencoded value.
err:C0061 Occurs if the name of any encoded parameter name is not a valid XML name (without a colon).

Examples

This example is predicated on the notion that the pipeline is being used to implement some web service end point. The web server packages up the request in XML and passes it on to our pipeline.

  1 <p:pipeline xmlns:p="http://www.w3.org/ns/xproc"
                version="1.0">
    
      <p:www-form-urldecode xmlns:ws="http://example.com/webservice">
  5     <p:with-option name="value"
                       select="/ws:request/ws:params"/>
      </p:www-form-urldecode>
    </p:pipeline>
Input Output
1 <request xmlns="http://example.com/webservice">
<uri>http://example.com/service</uri>
<params>a=b&amp;c=d&amp;test=this%20or%20that</params>
</request>
 
1 <c:param-set xmlns:c="http://www.w3.org/ns/xproc-step">
<c:param name="a" value="b"/>
<c:param name="c" value="d"/>
<c:param name="test" value="this or that"/>
5 </c:param-set>

A web service that simply returned its parameters decoded into a c:param-set would be pretty pointless. In a real pipeline, they'd probably be passed to p:xslt or some other step.