Difference between revisions of "Web Module"
Line 109: | Line 109: | ||
==web:response-header== | ==web:response-header== | ||
+ | |||
+ | {{Mark|Updated with Version 9.0}}: third argument added; no default parameters. | ||
{| width='100%' | {| width='100%' | ||
|- | |- | ||
| 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||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/> |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Creates a [[RESTXQ#Response|RESTXQ response header]] | + | |Creates a [[RESTXQ#Response|RESTXQ response header]].<br/> |
− | Serialization parameters can be supplied via the <code>$output</code> | + | 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 top element with the <code>$atts</code> argument. |
* <code>media-type</code>: <code>application/octet-stream</code> | * <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: | 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: | ||
Line 124: | Line 126: | ||
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | * The function call <code>web:response-header()</code> returns | + | * The function call <code>web:response-header()</code> returns: |
<pre class="brush:xml"> | <pre class="brush: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"/> |
− | + | <output:serialization-parameters xmlns:output="http://www.w3.org/2010/xslt-xquery-serialization"/> | |
− | |||
− | <output:serialization-parameters xmlns:output="http://www.w3.org/2010/xslt-xquery-serialization" | ||
− | |||
− | |||
</rest:response> | </rest:response> | ||
</pre> | </pre> | ||
− | * | + | * The following function returns a media-type for binary data, a caching directive, and the OK status:<br/> |
+ | <pre class="brush: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 class="brush:xquery"> | <pre class="brush:xquery"> | ||
declare %rest:path('media/{$file}') function local:get($file) { | declare %rest:path('media/{$file}') function local:get($file) { | ||
Line 145: | Line 151: | ||
}; | }; | ||
</pre> | </pre> | ||
− | |||
|} | |} | ||
Line 162: | Line 167: | ||
=Changelog= | =Changelog= | ||
+ | |||
+ | ;Version 9.0 | ||
+ | |||
+ | * Updated: [[#web:response-header|web:response-header]]: third argument; no default parameters. | ||
;Version 8.4 | ;Version 8.4 |
Revision as of 10:40, 17 October 2017
This XQuery Module provides convenience functions for building web applications with RESTXQ.
Contents
Conventions
All functions in this module are assigned to the http://basex.org/modules/web
namespace, which is statically bound to the web
prefix.
All errors are assigned to the http://basex.org/errors
namespace, which is statically bound to the bxerr
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(item(), item()*)) as xs:string |
Summary | Creates a new URL from the specified $url string and the $parameters specified in a map. The keys and 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 | BXWE0001 : Specified URI is invalid.
|
Errors | BXWE0002 : Specified URI contains invalid XML characters.
|
web:redirect
Signatures | web:redirect($location as xs:string) as element(rest:response) web:redirect($location as xs:string, $parameters as map(item(), item()*)) as element(rest:response) |
Summary | Creates a RESTXQ redirection to the specified location. The returned response will only work if no other items are returned by the RESTXQ function. If $parameters are specified, they will be appended as query parameters to the URL as described for web:create-url.
|
Examples |
<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>
declare %updating %rest:path('/app/init') function local:init() { db:create('app', <root/>, 'root.xml'), db:output(web:redirect('/app/main')) }; declare %rest:path('/app/main') function local:update() { 'Stored documents: ' || count(db:open('app')) }; |
web:response-header
Template:Mark: third argument added; no default parameters.
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 |
<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) ) }; |
Errors
Code | Description |
---|---|
BXWE0001
|
Specified URL is invalid. |
BXWE0002
|
Specified URL contains invalid XML characters. |
Changelog
- Version 9.0
- Updated: web:response-header: third argument; no default parameters.
- Version 8.4
- Updated: web:response-header: serialization method
raw
was removed (now obsolete).
- Version 8.2
- Added: web:encode-url, web:decode-url.
The module was introduced with Version 8.1.