Bureaucrats, editor, reviewer, Administrators
13,554
edits
Changes
Jump to navigation
Jump to search
m
[[Category:XQuery]]
Text replacement - "syntaxhighlight" to "pre"
This [[Module Library|XQuery Module]] provides convenience functions for building web applications with [[Web ApplicationRESTXQ]]s with RESTXQ.
=Conventions=
All functions and errors in this module are assigned to the {{Code|<code><nowiki>http://basex.org/modules/web}} </nowiki></code> namespace, which is statically bound to the {{Code|web}} prefix.<br/>All errors are assigned to the {{Code|http://basex.org/errors}} namespace, which is statically bound to the {{Code|bxerr}} prefix.
=Functions=
==web:mediacontent-type==
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|web:<pre>web:content-type|( $path as xs:string|) as xs:string}}<br/pre>|-valign="top"
| '''Summary'''
|Returns the content type of a path by analyzing its file suffix. <code>application/octet-stream</code> is returned if the file suffix is unknown.
|-valign="top"
| '''Examples'''
|
* <code><nowiki>web:content-type("sample.mp3")</nowiki></code> returns <code>audio/mpeg</code>
|}
==web:create-url==
{| width='100%'
|- valign="top"
| width='120' | '''Signature'''
|<pre>web:create-url(
$href as xs:string,
$parameters as map(*),
$anchor as xs:string := ()
) as xs:string</pre>
|- valign="top"
| '''Summary'''
|Creates a new URL from the specified {{Code|$href}} string, query string <code>$parameters</code> and an optional {{Code|$anchor}} reference. The keys and values of the map entries will be converted to strings, URL-encoded (see {{Function||web:encode-url}}), and appended to the URL as query parameters. If a map entry has more than a single item, all of them will be appended as single parameters.
|- valign="top"
| '''Examples'''
|
* <code><nowiki>web:create-url('http://find.me', map { 'q': 'dog' })</nowiki></code> returns <code><nowiki>http://find.me?q=dog</nowiki></code>
* <code><nowiki>web:create-url('search', map { 'year': (2000,2001), 'title':() })</nowiki></code> returns <code>search?year=2000&year=2001</code>
|}
==web:encode-url==
{| width='100%'
|- valign="top"
| width='120' | '''Signature'''
|<pre>web:encode-url(
$string as xs:string
) as xs:string</pre>
|- valign="top"
| '''Summary'''
|Encodes a string to a URL. Spaces are rewritten to {{Code|+}}; {{Code|*}}, {{Code|-}}, {{Code|.}} and {{Code|_}} are adopted; and all other non-ASCII characters and special characters are percent-encoded.
|- valign="top"
| '''Examples'''
|
* <code><nowiki>web:encode-url("this is a test!.html")</nowiki></code> returns <code>this+is+a+test%21.html</code>.
|}
==web:decode-url==
{| width='100%'
|- valign="top"
| width='120' | '''Signature'''
|<pre>web:decode-url(
$string as xs:string
) as xs:string</pre>
|- valign="top"
| '''Summary'''
|Decodes a URL to the original string. Percent-encoded characters are decoded to their UTF8 codepoints, and {{Code|+}} characters are rewritten to spaces.
|- valign="top"
| '''Examples'''
|
* <code><nowiki>web:decode-url("%E6%97%A5%E6%9C%AC%E8%AA%9E")</nowiki></code> returns <code>日本語</code>.
|- valign="top"
| '''Errors'''
|{{Error|invalid|#Errors}} the string contains invalid XML characters.
|}
==web:forward==
{| width='100%'
|- valign="top"
| width='120' | '''Signature'''
|<pre>web:forward(
$path as xs:string,
$parameters as map(*) := ()
) as element(rest:forward)</pre>
|- valign="top"
| '''Summary'''
|Creates a server-side [[RESTXQ#Forwards and Redirects|RESTXQ forward request]] to the specified {{Code|$path}}:
* The client will not get notified of this forwarding.
* Supplied query parameters will be attached to parameters of the current request.
* The {{Code|$parameter}} argument is processed as described in {{Function||web:create-url}}.
|- valign="top"
| '''Examples'''
|
The function call <code><nowiki>web:forward('/a/b')</nowiki></code> creates the following result (which will be interpreted as forwarding if RESTXQ is used):
<pre lang="xml">
<rest:forward>/a/b</rest:forward>
</pre>
|}
==web:redirect==
{| width='100%'
|- valign="top"
| width='120' | '''Signature'''
|<pre>web:redirect(
$url as xs:string,
$parameters as map(*) := (),
$anchor as xs:string := ()
) as element(rest:response)</pre>
|- valign="top"
| '''Summary'''
|Creates a [[RESTXQ#Forwards and Redirects|RESTXQ redirection]] to the specified {{Code|$url}}. The returned response will only work if no other items are returned by the RESTXQ function.<br/>The {{Code|$parameters}} and {{Code|$anchor}} arguments are processed as described in (see {{Function||web:create-url}}).
|- valign="top"
| '''Examples'''
|
The query <code><nowiki>web:redirect('/a/b')</nowiki></code> returns the following result (which will be interpreted as redirection if RESTXQ is used):
<pre lang="xml">
<rest:response xmlns:rest="http://exquery.org/ns/restxq">
<http:response xmlns:http="http://expath.org/ns/http-client" status="302">
<http:header name="location" value="/a/b"/>
</http:response>
</rest:response>
</pre>
|}
==web:response-header==
{| width='100%'
|- valign="top"
| width='120' | '''Signature'''
|<pre>web:response-header(
$output as map(*)? := (),
$headers as map(*)? := (),
$atts as map(*)? := ()
) as element(rest:response)</pre>
|- valign="top"
| '''Summary'''
|Creates a [[RESTXQ#Response|RESTXQ response header]].<br/>
Serialization parameters and header values can be supplied via the <code>$output</code> and <code>$headers</code> arguments, and status and message attributes can be attached to the HTTP response element with the <code>$atts</code> argument.
* <code>media-type</code>: <code>application/octet-stream</code>
Header options can be supplied via the <code>$headers</code> argument. Empty string values can be specified to invalidate default values. By default, the following header options will be returned:
* <code>Cache-Control</code>: <code>max-age=3600,public</code>
|- valign="top"
| '''Examples'''
|
* The function call <code>web:response-header()</code> returns:
<pre lang="xml">
<rest:response xmlns:rest="http://exquery.org/ns/restxq">
<http:response xmlns:http="http://expath.org/ns/http-client"/>
<output:serialization-parameters xmlns:output="http://www.w3.org/2010/xslt-xquery-serialization"/>
</rest:response>
</pre>
* The following expression returns a media-type for binary data, a caching directive, and the OK status:<br/>
<pre lang='xquery'>
web:response-header(
map { 'media-type': 'application/octet-stream' },
map { 'Cache-Control': 'max-age=3600,public' },
map { 'status': 200, 'message': 'OK' }
)
</pre>
* The following RESTXQ function returns the contents of a file to the client with correct media type:<br/>
<pre lang='xquery'>
declare %rest:path('media/{$file}') function local:get($file) {
let $path := 'path/to/' || $file
return (
web:response-header(map { 'media-type': web:content-type($path) }),
file:read-binary($path)
)
};
</pre>
|}
==web:error==
{| width='100%'
|- valign="top"
| width='120' | '''Signature'''
|<pre>web:error(
$status as xs:integer,
$message as xs:string
) as none</pre>
|- valign="top"
| '''Summary'''
|Raises an error with the QName {{Code|rest:error}}, the specified {{Code|$message}} and the specified {{Code|$status}} as error value.<br/>Calls to this function are equivalent to <code>fn:error(xs:QName('rest:error'), $message, $status)</code>.
See [[RESTXQ#Raise Errors|RESTXQ: Raise Errors]] to learn how the function is helpful in web applications.
|- valign="top"
| '''Examples'''
|
* <code><nowiki>web:error(404, "The requested resource cannot be found.")</nowiki></code>
|- valign="top"
| '''Errors'''
|{{Error|status|#Errors}} The supplied status code is invalid.
|}
=Errors=
{| class="wikitable" width="100%"
! width="110"|Code
|Description
|- valign="top"
|{{Code|invalid}}
|A string contains invalid XML characters.
|- valign="top"
|{{Code|status}}
|The supplied status code is invalid.
|}
=Changelog=
;Version 9.3
* Added: {{Function||web:error}}, {{Function||web:forward}}
;Version 9.2
* Updated: {{Function||web:create-url}}, {{Function||web:redirect}}: third argument added.
;Version 9.0
* Updated: {{Function||web:response-header}}: third argument added; default parameters removed.
* Updated: error codes updated; errors now use the module namespace
;Version 8.4
* Updated: {{Function||web:response-header}}: serialization method <code>raw</code> was removed (now obsolete).
;Version 8.2
* Added: {{Function||web:encode-url}}, {{Function||web:decode-url}}.
The module was introduced with Version 8.1.
