Difference between revisions of "Web Module"

From BaseX Documentation
Jump to navigation Jump to search
Line 65: Line 65:
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|web:response-header|$path as xs:string|element(rest:response)}}<br/>
+
|{{Func|web:response-header||element(rest:response)}}<br/>{{Func|web:response-header|$headers as map(*)|element(rest:response)}}<br/>{{Func|web:response-header|$headers as map(*), $output as map(*)|element(rest:response)}}<br/>
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Creates a [[RESTXQ#Response|RESTXQ reponse header]] for the specified <code>$file</code> with the correct mime-type and some caching directives. The output will only be correctly evaluated if no other items are returned before the header.
+
|Creates a [[RESTXQ#Response|RESTXQ reponse header]] with a default caching directive and default serialization parameters.<br/>
 +
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>
 +
<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:
 +
* <code>media-type</code>: <code>application/octet-stream</code>
 +
* <code>method</code>: <code>raw</code>
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
−
|If the following RESTXQ function is called…<br/>
+
|
−
<pre class="brush:xquery">
+
* The function call <code>web:response-header()</code> returns the following response element:
−
declare %rest:path('image/{$image}') function local:get($image) {
 
−
  let $path := 'path/to/' || $image
 
−
  return (
 
−
    web:response-header($path),
 
−
    file:read-binary($path)
 
−
  )
 
−
};
 
−
</pre>
 
−
…an image with the specified name (if available) will be sent back to the client:<br/>
 
 
<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" status="302">
+
   <http:response xmlns:http="http://expath.org/ns/http-client">
 
     <http:header name="Cache-Control" value="max-age=3600,public"/>
 
     <http:header name="Cache-Control" value="max-age=3600,public"/>
 
   </http:response>
 
   </http:response>
 
   <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">
−
     <output:media-type value="image/png"/>
+
     <output:media-type value="application/octet-stream"/>
 
     <output:method value="raw"/>
 
     <output:method value="raw"/>
 
   </output:serialization-parameters>
 
   </output:serialization-parameters>
−
</rest:response>,
+
</rest:response>
−
...
+
</pre>
 +
* If the following RESTXQ function is called by a web browser…<br/>
 +
<pre class="brush: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)
 +
  )
 +
};
 
</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).
 
|}
 
|}
  

Revision as of 12:25, 28 March 2015

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(*)) 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, URI-encoded, 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:redirect

Signatures web:redirect($location as xs:string) as element(rest:response)
Summary Creates a RESTXQ redirection to the specified location. Redirects will only work if no other items are returned.
Examples The query web:redirect('/a/b') returns the following response element: 
<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

Signatures web:response-header() as element(rest:response)
web:response-header($headers as map(*)) as element(rest:response)
web:response-header($headers as map(*), $output as map(*)) as element(rest:response)
Summary Creates a RESTXQ reponse header with a default caching directive and default serialization parameters.

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


Serialization parameters can be supplied via the $output argument. Empty string values can be specified to invalidate default values. By default, the following serialization parameters will be returned:

  • media-type: application/octet-stream
  • method: raw
Examples
  • The function call web:response-header() returns the following response element:
<rest:response xmlns:rest="http://exquery.org/ns/restxq">
  <http:response xmlns:http="http://expath.org/ns/http-client">
    <http:header name="Cache-Control" value="max-age=3600,public"/>
  </http:response>
  <output:serialization-parameters xmlns:output="http://www.w3.org/2010/xslt-xquery-serialization">
    <output:media-type value="application/octet-stream"/>
    <output:method value="raw"/>
  </output:serialization-parameters>
</rest:response>
  • If the following RESTXQ function is called by a web browser…
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)
  )
};

…a file resource with the correct content-type will be returned to user (provided that it exists in the web server's file system).

Changelog

The module was introduced with Version 8.1.

Retrieved from "http://docs.basex.org/index.php?title=Web_Module&oldid=11626"