Difference between revisions of "Web Module"

From BaseX Documentation
Jump to navigation Jump to search
Line 28: Line 28:
 
|-
 
|-
 
| 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(item(), item()*)|xs:string}}<br/>
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''

Revision as of 15:38, 24 June 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(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(*)) 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 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 response 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).

Errors

Code Description
BXWE0001 Specified URL is invalid.
BXWE0002 Specified URL contains invalid XML characters.

Changelog

Version 8.2

The module was introduced with Version 8.1.