Difference between revisions of "Web Module"

From BaseX Documentation
Jump to navigation Jump to search
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]] with a default caching directive and default serialization parameters.<br/>
+
|Creates a [[RESTXQ#Response|RESTXQ response header]].<br/>
−
Serialization parameters can be supplied via the <code>$output</code> argument. Empty string values can be specified to invalidate default values. By default, the following serialization parameters will be returned:
+
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 following response element:
+
* 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"/>
−
    <http:header name="Cache-Control" value="max-age=3600,public"/>
+
   <output:serialization-parameters xmlns:output="http://www.w3.org/2010/xslt-xquery-serialization"/>
−
  </http:response>
 
−
   <output:serialization-parameters xmlns:output="http://www.w3.org/2010/xslt-xquery-serialization">
 
−
    <output:media-type value="application/octet-stream"/>
 
−
  </output:serialization-parameters>
 
 
</rest:response>
 
</rest:response>
 
</pre>
 
</pre>
−
* If the following RESTXQ function is called by a web browser…<br/>
+
* 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>
−
…a file resource with the correct content-type will be returned to user (provided that it exists in the web server's file system).
 
 
|}
 
|}
  
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.

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:content-type("sample.mp3") returns audio/mpeg

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:create-url('http://find.me', map { 'q': 'dog' }) returns http://find.me?q=dog
  • web:create-url('search', map { 'year': (2000,2001), 'title':() }) returns search?year=2000&year=2001

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:encode-url("this is a test!.html") returns this+is+a+test%21.html.

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
  • web:decode-url("%E6%97%A5%E6%9C%AC%E8%AA%9E") returns 日本語.
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
  • The query web:redirect('/a/b') returns the following result (which will be interpreted as redirection if RESTXQ is used):
<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>
  • The first RESTXQ function creates an initial database, and redirects to a second function that will access this database:
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 $output and $headers arguments, and status and message attributes can be attached to the top element with the $atts argument.

  • media-type: application/octet-stream

Header options can be supplied via the $headers argument. Empty string values can be specified to invalidate default values. By default, the following header options will be returned:

  • Cache-Control: max-age=3600,public
Examples
  • The function call web:response-header() returns:
<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>
  • The following function returns a media-type for binary data, a caching directive, and the OK status:
web:response-header(
  map { 'media-type': 'application/octet-stream' },
  map { 'Cache-Control': 'max-age=3600,public' },
  map { 'status': 200, 'message': 'OK' }
)
  • The following RESTXQ function returns the contents of a file to the client with correct media type:
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
Version 8.4
Version 8.2

The module was introduced with Version 8.1.

Retrieved from "https://old.docs.basex.org/index.php?title=Web_Module&oldid=13320"