Short URLs (XWiki.org)

1

A short URL is an XWiki URL without its ##xwiki##, ##bin## and ##view## parts: ##server.com/Sandbox/WebHome## instead of ##server.com/xwiki/bin/view/Sandbox/WebHome##. Shortening them changes both the URLs XWiki accepts and the URLs it generates.

2

3

== The three parts to remove ==

4

5

A default XWiki URL carries three removable parts, each removed by a different mechanism. They are independent, so you can remove one, two or all three.

6

7

|=Part|=Example|=What it is|=How to remove it

8

|Application name|##/xwiki/##|The context path the servlet container gives the XWiki web application.|[[Deploy XWiki as the Root Web Application>>doc:documentation.xs.admin.configuration.short-urls.deploy-root-webapp.WebHome]]

9

|Servlet mapping|##/bin/##|The path the Action Servlet is mapped to, which tells the container which servlet handles the request.|One of the two approaches below.

10

|Action name|##/view/##|What to do with the document: view, edit, delete, and so on.|[[Hide the View Action in URLs>>doc:documentation.xs.admin.configuration.short-urls.hide-view-action.WebHome]]

11

12

Every configuration key these pages set is listed on [[URL Configuration Properties>>doc:documentation.xs.admin.configuration.short-urls.properties.WebHome]].

13

14

== Removing the servlet mapping ==

15

16

This is the only part that configuration alone cannot remove. XWiki maps its Action Servlet to ##/bin/*##, ##/wiki/*## (the prefix of path-based subwikis), ##/testbin/*## and ##/xwiki/*##, so a request carrying none of them has to be rewritten into one of them before it reaches the servlet. Two places can do that, which is the choice to make:

17

18

* [[Configure Short URLs with the UrlRewriteFilter>>doc:documentation.xs.admin.configuration.short-urls.rewrite-filter.WebHome]], a servlet filter installed inside the XWiki web application. Use it when nothing sits in front of XWiki.

19

* [[Configure Short URLs with Apache HTTP Server>>doc:documentation.xs.admin.configuration.short-urls.apache.WebHome]] or [[Configure Short URLs with Nginx>>doc:documentation.xs.admin.configuration.short-urls.nginx.WebHome]], where the web server rewrites the path before the request reaches the servlet container. Use one of these when the instance is already behind that web server.

@startuml

!theme bluegray

skinparam nodesep 30

skinparam ranksep 45

actor "Browser requests\nserver.com/Sandbox/WebHome" as B

28

rectangle "Apache HTTP Server or Nginx\nrewrites the path" as WS

29

rectangle "UrlRewriteFilter\nin the XWiki web application\nrewrites the path" as F

30

rectangle "Action Servlet\nmapped to /bin/*" as A

31

card "Sandbox.WebHome is displayed" as P

32

33

B --> WS : XWiki already behind a web server

34

B --> F : nothing in front of XWiki

35

WS --> A : /bin/view/Sandbox/WebHome

36

F --> A : /bin/view/Sandbox/WebHome

A --> P

@enduml

== What must not reach the Action Servlet ==

42

43

Whatever performs the rewriting has to leave alone the paths XWiki serves by other means, or it breaks static resources, the REST API and file uploads.

44

45

|=Path|=Why it must be excluded

46

|##resources##, ##skins##|Static resource types, which XWiki deliberately lets fall through to the servlet container's default servlet.

47

|##webjars##, ##tmp##|Resource types with their own handlers: web application libraries, and temporary resources such as generated diagrams.

48

|##rest##|The REST API, served by its own servlet.

49

|##redirect##|The web application's welcome file, which sends a URL carrying no page to the home page.

50

|##bin##, ##wiki##, ##testbin##, ##xwiki##|Already mapped to the Action Servlet.

51

|##asyncrenderer##, ##authenticate##, ##jcaptcha##, ##job##|Each is claimed by another resource handler.

52

|##websocket##|The prefix of the WebSocket end-points, which the realtime editing features connect to.

53

|##robots.txt##|Served as a static file when the instance provides one.

54

55

== Why a single catch-all mapping is not enough ==

56

57

The obvious shortcut is to map the Action Servlet to ##/*## in ##web.xml## and change nothing else. It does not work: ##/skins## and ##/resources## match that mapping too, and ##web.xml## leaves them unmapped precisely so that the container's default servlet serves them. Excluding them in the rewrite rules, or serving them from the web server in front of XWiki, is what the two approaches above do instead. Mapping the two paths to the container's own default servlet is not a way out either: on Tomcat that servlet takes no parameter for changing the directory it serves from, so you would have to write one of your own.

58

59

== What you end up with ==

60

61

|=URL|=Page shown

62

|##server.com/Sandbox/WebHome##|##Sandbox.WebHome##

63

|##server.com/Sandbox/##|##Sandbox.WebHome##

64

|##server.com/Document##|##Document.WebHome##