Difference between revisions of "Web Module"
m (Text replacement - "\[\[#([^]:]+:[^|]+)\|([^]:]+:[^|]+)\]\]" to "{{Function||$1}}") |
|||
Line 10: | Line 10: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|web:content-type|$path as xs:string|xs:string}}<br/> | |{{Func|web:content-type|$path as xs:string|xs:string}}<br/> | ||
− | |- | + | |- 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 25: | Line 25: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|web:create-url|$url as xs:string, $parameters as map(*)|xs:string}}<br/>{{Func|web:create-url|$url as xs:string, $parameters as map(*), $anchor as xs:string|xs:string}}<br/> | |{{Func|web:create-url|$url as xs:string, $parameters as map(*)|xs:string}}<br/>{{Func|web:create-url|$url as xs:string, $parameters as map(*), $anchor as xs:string|xs:string}}<br/> | ||
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Creates a new URL from the specified <code>$url</code> 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. | |Creates a new URL from the specified <code>$url</code> 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 41: | Line 41: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|web:encode-url|$string as xs:string|xs:string}}<br/> | |{{Func|web:encode-url|$string as xs:string|xs:string}}<br/> | ||
− | |- | + | |- 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 56: | Line 56: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|web:decode-url|$string as xs:string|xs:string}}<br/> | |{{Func|web:decode-url|$string as xs:string|xs:string}}<br/> | ||
− | |- | + | |- 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. | ||
Line 74: | Line 74: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|web:forward|$path as xs:string|element(rest:forward)}}<br/>{{Func|web:forward|$path as xs:string, $parameters as map(*)|element(rest:forward)}} | |{{Func|web:forward|$path as xs:string|element(rest:forward)}}<br/>{{Func|web:forward|$path as xs:string, $parameters as map(*)|element(rest:forward)}} | ||
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Creates a server-side [[RESTXQ#Forwards and Redirects|RESTXQ forward request]] to the specified {{Code|$path}}: | |Creates a server-side [[RESTXQ#Forwards and Redirects|RESTXQ forward request]] to the specified {{Code|$path}}: | ||
Line 83: | Line 83: | ||
* Supplied query parameters will be attached to parameters of the current request. | * 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}}. | * The {{Code|$parameter}} argument is processed as described in {{Function||web:create-url}}. | ||
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
Line 95: | Line 95: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|web:redirect|$url as xs:string|element(rest:response)}}<br/>{{Func|web:redirect|$url as xs:string, $parameters as map(*)|element(rest:response)}}<br/>{{Func|web:redirect|$url as xs:string, $parameters as map(*), $anchor as xs:string|element(rest:response)}}<br/> | |{{Func|web:redirect|$url as xs:string|element(rest:response)}}<br/>{{Func|web:redirect|$url as xs:string, $parameters as map(*)|element(rest:response)}}<br/>{{Func|web:redirect|$url as xs:string, $parameters as map(*), $anchor as xs:string|element(rest:response)}}<br/> | ||
− | |- | + | |- 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 {{Function||web:create-url}}). | |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''' | ||
| | | | ||
Line 117: | Line 117: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|web:response-header||element(rest:response)}}<br/>{{Func|web:response-header|$output as map(*)?|element(rest:response)}}<br/>{{Func|web:response-header|$output as map(*)?, $headers as map(*)?|element(rest:response)}}<br/>{{Func|web:response-header|$output as map(*)?, $headers as map(*)?, $atts as map(*)?|element(rest:response)}}<br/> | |{{Func|web:response-header||element(rest:response)}}<br/>{{Func|web:response-header|$output as map(*)?|element(rest:response)}}<br/>{{Func|web:response-header|$output as map(*)?, $headers as map(*)?|element(rest:response)}}<br/>{{Func|web:response-header|$output as map(*)?, $headers as map(*)?, $atts as map(*)?|element(rest:response)}}<br/> | ||
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Creates a [[RESTXQ#Response|RESTXQ response header]].<br/> | |Creates a [[RESTXQ#Response|RESTXQ response header]].<br/> | ||
Line 127: | Line 127: | ||
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''' | ||
| | | | ||
Line 160: | Line 160: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|web:error|$status as xs:integer, $message as xs:string|none}}<br/> | |{{Func|web:error|$status as xs:integer, $message as xs:string|none}}<br/> | ||
− | |- | + | |- 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.<br/>Calls to this function are equivalent to <code>fn:error(xs:QName('rest:error'), $message, $status)</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 Errors|RESTXQ: Raise Errors]] to learn how the function is helpful in web applications. | See [[RESTXQ#Raise Errors|RESTXQ: Raise Errors]] to learn how the function is helpful in web applications. | ||
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
* <code><nowiki>web:error(404, "The requested resource cannot be found.")</nowiki></code> | * <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 182: | Line 182: | ||
! 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. |
Revision as of 14:20, 20 July 2022
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
Signatures | 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
Signatures | web:create-url($url as xs:string, $parameters as map(*)) as xs:string web:create-url($url as xs:string, $parameters as map(*), $anchor as xs:string) as xs:string |
Summary | Creates a new URL from the specified $url 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
Signatures | 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
Signatures | 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
Signatures | web:forward($path as xs:string) as element(rest:forward) 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
Signatures | web:redirect($url as xs:string) as element(rest:response) web:redirect($url as xs:string, $parameters as map(*)) as element(rest:response) 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
Signatures | web:response-header() as element(rest:response) web:response-header($output as map(*)?) as element(rest:response) web:response-header($output as map(*)?, $headers as map(*)?) as element(rest:response) 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>
<syntaxhighlight lang="xquery"> web:response-header( map { 'media-type': 'application/octet-stream' }, map { 'Cache-Control': 'max-age=3600,public' }, map { 'status': 200, 'message': 'OK' } ) </syntaxhighlight>
<syntaxhighlight 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
Signatures | 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.