diff --git a/src/main/xar-resources/data/urlrewrite/listings/listing-1.txt b/src/main/xar-resources/data/urlrewrite/listings/listing-1.txt new file mode 100644 index 00000000..45d007fd --- /dev/null +++ b/src/main/xar-resources/data/urlrewrite/listings/listing-1.txt @@ -0,0 +1,13 @@ +xquery version "3.0"; + +declare variable $exist:path external; +declare variable $exist:resource external; +declare variable $exist:controller external; +declare variable $exist:prefix external; +declare variable $exist:root external; + + + + + + \ No newline at end of file diff --git a/src/main/xar-resources/data/urlrewrite/listings/listing-2.txt b/src/main/xar-resources/data/urlrewrite/listings/listing-2.txt index a7f641ad..c7d37f2c 100644 --- a/src/main/xar-resources/data/urlrewrite/listings/listing-2.txt +++ b/src/main/xar-resources/data/urlrewrite/listings/listing-2.txt @@ -1,8 +1,14 @@ -let $params := subsequence(analyze-string($exist:path, '^/?(.*)/([^/]+)$')//fn:group, 2) -return - - - - - - \ No newline at end of file +xquery version "3.0"; + +declare variable $exist:path external; +declare variable $exist:resource external; +declare variable $exist:controller external; +declare variable $exist:prefix external; +declare variable $exist:root external; + + + + + + + \ No newline at end of file diff --git a/src/main/xar-resources/data/urlrewrite/urlrewrite.xml b/src/main/xar-resources/data/urlrewrite/urlrewrite.xml index 349ede2a..33320e3b 100644 --- a/src/main/xar-resources/data/urlrewrite/urlrewrite.xml +++ b/src/main/xar-resources/data/urlrewrite/urlrewrite.xml @@ -19,6 +19,34 @@ + + Introduction + When designing web applications, a common rule is to provide meaningful URIs to the user. Internally an application usually combines XQuery modules, + HTML files, data and other resources, organized into a hierarchical structure. Direct links to such deeply nested resources would result in very long URIs. You may not want to expose those structures to the users, but provide + short and human-readable URIs instead. + Let's contemplate the following scenario: the XML documents your app should display through a web page are contained in a sub-collection + called data. For example, the document you are currently reading resides in data/urlrewrite.xml within the documentation collection. The direct URL pointing to this document would thus be /exist/apps/doc/data/urlrewrite.xml. We do not want to show the user the raw XML though. Instead users should get a properly formatted HTML version of the text, accessible through a simple URL like /exist/apps/doc/urlrewrite. + To achieve this we need a mechanism to map or rewrite a given URL to an application specific endpoint. So in the simplest case, calling + /exist/apps/doc/urlrewrite would trigger an XQuery which is able to locate the source document, transform it into HTML and return the result. In eXist this mapping is done through a special XQuery named controller.xql, which is called at the start of the request processing. + controller.xql is invoked for all URL paths targeting the collection it resides in. It is supposed to return an + XML fragment describing how the request is to be further processed. To do this, controller.xql has access to a number + of variables pre-filled with details about the request. One of those variables is $exist:resource, containing the name of the resource (without path components) the request tries to access. Another one is $exist:controller which points to the collection the controller.xql is located in. + For example, one may want to direct all requests to /exist/apps/doc/{resource} to an XQuery, transform.xql, which is responsible for converting the XML content into HTML: + + This example controller returns a simple dispatch fragment only. This fragment will be passed back to the URL rewriting framework once the controller XQuery has been executed. The forward element instructs the framework to call the URL modules/transform.xql relative to the collection in which the controller resides. It adds a request parameter, named doc, which translates the requested resource into an actual document path to be transformed by modules/transform.xql. + Real world controllers are typically more complicated and may contain arbitrary XQuery code to distinguish between different scenarios. Basically, the URL rewriting framework allows you to turn simple requests into complex processing pipelines, involving any number of steps. For example, let us split above dispatch fragment into a pipeline involving two steps: + + + load the resource to be transformed + + + pass the content of the resource to modules/transform.xql + + + + Every dispatch fragment must contain at least one step, followed by an optional view element grouping any number of follow up steps. In the example, the first forward step simply loads the XML document requested and returns its content. The output of the first step is passed to the second step via the HTTP request (and can be accessed via the XQuery function request:get-data()). + + Basics