Difference between revisions of "Web Module"
m (Text replacement - "syntaxhighlight" to "pre") |
|||
(24 intermediate revisions by the same user not shown) | |||
Line 10: | Line 10: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>web:content-type( |
− | |- | + | $path as xs:string |
+ | ) as xs:string</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''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. | |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''' | | '''Examples''' | ||
| | | | ||
Line 23: | Line 25: | ||
==web:create-url== | ==web:create-url== | ||
− | |||
− | |||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | 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''' | | '''Summary''' | ||
− | |Creates a new URL from the specified | + | |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''' | | '''Examples''' | ||
| | | | ||
Line 43: | Line 47: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>web:encode-url( |
− | |- | + | $string as xs:string |
+ | ) as xs:string</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''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. | |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''' | | '''Examples''' | ||
| | | | ||
Line 58: | Line 64: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>web:decode-url( |
− | |- | + | $string as xs:string |
+ | ) as xs:string</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
|Decodes a URL to the original string. Percent-encoded characters are decoded to their UTF8 codepoints, and {{Code|+}} characters are rewritten to spaces. | |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''' | | '''Examples''' | ||
| | | | ||
* <code><nowiki>web:decode-url("%E6%97%A5%E6%9C%AC%E8%AA%9E")</nowiki></code> returns <code>日本語</code>. | * <code><nowiki>web:decode-url("%E6%97%A5%E6%9C%AC%E8%AA%9E")</nowiki></code> returns <code>日本語</code>. | ||
− | |- | + | |- valign="top" |
| '''Errors''' | | '''Errors''' | ||
|{{Error|invalid|#Errors}} the string contains invalid XML characters. | |{{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== | ==web:redirect== | ||
− | |||
− | |||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | 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''' | | '''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 | + | |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''' | | '''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 | + | <pre lang="xml"> |
<rest:response xmlns:rest="http://exquery.org/ns/restxq"> | <rest:response xmlns:rest="http://exquery.org/ns/restxq"> | ||
<http:response xmlns:http="http://expath.org/ns/http-client" status="302"> | <http:response xmlns:http="http://expath.org/ns/http-client" status="302"> | ||
Line 94: | Line 128: | ||
</http:response> | </http:response> | ||
</rest:response> | </rest:response> | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
</pre> | </pre> | ||
|} | |} | ||
Line 111: | Line 134: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>web:response-header( |
− | |- | + | $output as map(*)? := (), |
+ | $headers as map(*)? := (), | ||
+ | $atts as map(*)? := () | ||
+ | ) as element(rest:response)</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
|Creates a [[RESTXQ#Response|RESTXQ response header]].<br/> | |Creates a [[RESTXQ#Response|RESTXQ response header]].<br/> | ||
Line 121: | Line 148: | ||
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: | 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> | * <code>Cache-Control</code>: <code>max-age=3600,public</code> | ||
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
* The function call <code>web:response-header()</code> returns: | * The function call <code>web:response-header()</code> returns: | ||
− | <pre | + | <pre lang="xml"> |
<rest:response xmlns:rest="http://exquery.org/ns/restxq"> | <rest:response xmlns:rest="http://exquery.org/ns/restxq"> | ||
<http:response xmlns:http="http://expath.org/ns/http-client"/> | <http:response xmlns:http="http://expath.org/ns/http-client"/> | ||
Line 132: | Line 159: | ||
</pre> | </pre> | ||
* The following expression returns a media-type for binary data, a caching directive, and the OK status:<br/> | * The following expression returns a media-type for binary data, a caching directive, and the OK status:<br/> | ||
− | <pre | + | <pre lang='xquery'> |
web:response-header( | web:response-header( | ||
map { 'media-type': 'application/octet-stream' }, | map { 'media-type': 'application/octet-stream' }, | ||
Line 140: | Line 167: | ||
</pre> | </pre> | ||
* The following RESTXQ function returns the contents of a file to the client with correct media type:<br/> | * The following RESTXQ function returns the contents of a file to the client with correct media type:<br/> | ||
− | <pre | + | <pre lang='xquery'> |
declare %rest:path('media/{$file}') function local:get($file) { | declare %rest:path('media/{$file}') function local:get($file) { | ||
let $path := 'path/to/' || $file | let $path := 'path/to/' || $file | ||
Line 152: | Line 179: | ||
==web:error== | ==web:error== | ||
− | |||
− | |||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>web:error( |
− | |- | + | $status as xs:integer, |
+ | $message as xs:string | ||
+ | ) as none</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | |Raises an error with the QName {{Code|rest:error}}, the specified {{Code|$message}} and the specified {{Code|$status}} as error value. Calls to this function are equivalent to <code> | + | |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 | + | See [[RESTXQ#Raise Errors|RESTXQ: Raise Errors]] to learn how the function is helpful in web applications. |
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | * <code><nowiki>web: | + | * <code><nowiki>web:error(404, "The requested resource cannot be found.")</nowiki></code> |
− | |- | + | |- valign="top" |
| '''Errors''' | | '''Errors''' | ||
|{{Error|status|#Errors}} The supplied status code is invalid. | |{{Error|status|#Errors}} The supplied status code is invalid. | ||
Line 178: | Line 206: | ||
! width="110"|Code | ! width="110"|Code | ||
|Description | |Description | ||
− | |- | + | |- valign="top" |
|{{Code|invalid}} | |{{Code|invalid}} | ||
|A string contains invalid XML characters. | |A string contains invalid XML characters. | ||
− | |- | + | |- valign="top" |
|{{Code|status}} | |{{Code|status}} | ||
|The supplied status code is invalid. | |The supplied status code is invalid. | ||
Line 189: | Line 217: | ||
;Version 9.3 | ;Version 9.3 | ||
− | + | * Added: {{Function||web:error}}, {{Function||web:forward}} | |
− | * Added: | ||
;Version 9.2 | ;Version 9.2 | ||
− | + | * Updated: {{Function||web:create-url}}, {{Function||web:redirect}}: third argument added. | |
− | * Updated: | ||
;Version 9.0 | ;Version 9.0 | ||
− | + | * Updated: {{Function||web:response-header}}: third argument added; default parameters removed. | |
− | * Updated: | ||
* Updated: error codes updated; errors now use the module namespace | * Updated: error codes updated; errors now use the module namespace | ||
;Version 8.4 | ;Version 8.4 | ||
− | + | * Updated: {{Function||web:response-header}}: serialization method <code>raw</code> was removed (now obsolete). | |
− | * Updated: | ||
;Version 8.2 | ;Version 8.2 | ||
− | + | * Added: {{Function||web:encode-url}}, {{Function||web:decode-url}}. | |
− | * Added: | ||
The module was introduced with Version 8.1. | The module was introduced with Version 8.1. |
Latest revision as of 18:39, 1 December 2023
This XQuery Module provides convenience functions for building web applications with RESTXQ.
Contents
Conventions[edit]
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[edit]
web:content-type[edit]
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[edit]
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[edit]
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[edit]
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[edit]
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 <rest:forward>/a/b</rest:forward>
|
web:redirect[edit]
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 <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>
|
web:response-header[edit]
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 |
<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>
web:response-header(
map { 'media-type': 'application/octet-stream' },
map { 'Cache-Control': 'max-age=3600,public' },
map { 'status': 200, 'message': 'OK' }
)
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)
)
};
|
web:error[edit]
Signature | 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[edit]
Code | Description |
---|---|
invalid
|
A string contains invalid XML characters. |
status
|
The supplied status code is invalid. |
Changelog[edit]
- 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.