Web Module
This XQuery Module provides convenience functions for building web applications with RESTXQ.
Contents
Conventions
All functions and errors in this module are assigned to the http://basex.org/modules/web
namespace, which is statically bound to the web
prefix.
Functions
web:content-type
Signature | web:content-type( $path as xs:string ) as xs:string |
Summary | Returns the content type of a path by analyzing its file suffix. application/octet-stream is returned if the file suffix is unknown.
|
Examples |
|
web:create-url
Signature | web:create-url( $href as xs:string, $parameters as map(*), $anchor as xs:string := () ) as xs:string |
Summary | Creates a new URL from the specified $href string, query string $parameters and an optional $anchor reference. The keys and values of the map entries will be converted to strings, URL-encoded (see 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.
|
Examples |
|
web:encode-url
Signature | web:encode-url( $string as xs:string ) as xs:string |
Summary | Encodes a string to a URL. Spaces are rewritten to + ; * , - , . and _ are adopted; and all other non-ASCII characters and special characters are percent-encoded.
|
Examples |
|
web:decode-url
Signature | web:decode-url( $string as xs:string ) as xs:string |
Summary | Decodes a URL to the original string. Percent-encoded characters are decoded to their UTF8 codepoints, and + characters are rewritten to spaces.
|
Examples |
|
Errors | invalid : the string contains invalid XML characters.
|
web:forward
Signature | web:forward( $path as xs:string, $parameters as map(*) := () ) as element(rest:forward) |
Summary | Creates a server-side RESTXQ forward request to the specified $path :
|
Examples |
The function call |
web:redirect
Signature | web:redirect( $url as xs:string, $parameters as map(*) := (), $anchor as xs:string := () ) as element(rest:response) |
Summary | Creates a RESTXQ redirection to the specified $url . The returned response will only work if no other items are returned by the RESTXQ function.The $parameters and $anchor arguments are processed as described in (see web:create-url ).
|
Examples |
The query <http:response xmlns:http="http://expath.org/ns/http-client" status="302"> <http:header name="location" value="/a/b"/> </http:response> </rest:response> </syntaxhighlight> |
web:response-header
Signature | web:response-header( $output as map(*)? := (), $headers as map(*)? := (), $atts as map(*)? := () ) as element(rest:response) |
Summary | Creates a RESTXQ response header. Serialization parameters and header values can be supplied via the
Header options can be supplied via the
|
Examples |
<syntaxhighlight 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> </syntaxhighlight>
web:response-header(
map { 'media-type': 'application/octet-stream' },
map { 'Cache-Control': 'max-age=3600,public' },
map { 'status': 200, 'message': 'OK' }
)
</syntaxhighlight>
* 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)
)
};
</syntaxhighlight>
|}
==web:error==
{| width='100%'
|- valign="top"
| width='120' | '''Signature'''
|<pre>web:error(
$status as xs:integer,
$message as xs:string
) as none
|
Summary | Raises an error with the QName rest:error , the specified $message and the specified $status as error value.Calls to this function are equivalent to fn:error(xs:QName('rest:error'), $message, $status) .
See RESTXQ: Raise Errors to learn how the function is helpful in web applications. |
Examples |
|
Errors | status : The supplied status code is invalid.
|
Errors
Code | Description |
---|---|
invalid
|
A string contains invalid XML characters. |
status
|
The supplied status code is invalid. |
Changelog
- Version 9.3
- Added:
web:error
,web:forward
- Version 9.2
- Updated:
web:create-url
,web:redirect
: third argument added.
- Version 9.0
- Updated:
web:response-header
: third argument added; default parameters removed. - Updated: error codes updated; errors now use the module namespace
- Version 8.4
- Updated:
web:response-header
: serialization methodraw
was removed (now obsolete).
- Version 8.2
- Added:
web:encode-url
,web:decode-url
.
The module was introduced with Version 8.1.