Skip to Content

Wiki source code of Short XWiki URLs

Version 44.3 by Vincent Massol on 2014/11/28
Hide last authors
Manuel Smeria 19.4 1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
Jerome 14.1 4
Manuel Smeria 19.4 5 This tutorial shows you how to tune your XWiki platform by replacing the default URL scheme with a shorter scheme.
Jerome 15.1 6
Jerome 14.1 7 {{info}}
8 A short URL is an URL without the ##xwiki/bin/view## parts.
9 {{/info}}
maalej 2.1 10
Dmitry Bakbardin 20.1 11 = I. Application name =
maalej 1.1 12
Jerome 14.1 13 The ##/xwiki/## part of the URL is the application name. It identifies the application that should process the request, and it allows a container to host more than one application. To change it you must refer to your container's documentation and find how to map the context path of a web application. For example on Tomcat it's enough to simply deploy the XWiki webapp in the ##webapps## directory, in a sub directory named after the application name you wish to use (e.g. ##webapps/myappname##).
maalej 1.1 14
Vincent Massol 26.1 15 A special case is when deploying XWiki as the ROOT application, which actually allows the application name part to be empty, so an URL can take the form ##server.com/bin/view/Space/Document##. Achieving this depends on the container, as there's no standard regarding the ROOT application. For example:
Guillaume Fenollar 43.1 16
Vincent Massol 26.1 17 * in Tomcat, with the default configuration, all it takes is to deploy the XWiki web application in ##webapps##, in a sub directory named ##ROOT## (i.e. ##webapps/ROOT##).
18 * In Jetty, with the default configuration, all it takes is to deploy the XWiki web application in ##webapps##, in a sub directory named ##root##. Note that if you're using the Standalone distribution (which packages Jetty and HSQLDB) then you'll also need to:
19 ** Remove the existing ##webapps/root## directory which contains a redirect Servlet that automatically redirects root URLs to the ##xwiki## context. You won't need that anymore.
20 ** Rename the existing ##webapps/xwiki## directory into ##webapps/root##.
21 ** Remove the ##jetty/contexts/xwiki.xml## file and thus keep only the ##jetty/contexts/root.xml## file. Otherwise you'll get a warning in the console.
Vincent Massol 10.2 22
Vincent Massol 26.1 23 Refer to your container's documentation for more details.
24
Dmitry Bakbardin 20.1 25 = II. Servlet mapping name =
maalej 1.1 26
Vincent Massol 29.1 27 The second part is the hardest part to remove. It identifies the servlet that should process the page, which, for ##/bin/##, is the Struts servlet. Generically speaking, to get rid of ##/bin/##, you need to configure your system so that URLs matching ##/*## are mapped to the Struts Servlet (by default only ##/bin/*## URLs are mapped to the Struts Servlet).
maalej 1.1 28
Vincent Massol 35.1 29 However you need to be careful that the following prefixes do NOT go through the Struts Servlet (see your ##web.xml## to check their current mappings):
Guillaume Fenollar 43.1 30
Vincent Massol 29.1 31 * ##/resources/*## and ##/skins/*##: Statically served resources. These need to be served directly as static resources.
Vincent Massol 35.1 32 * ##/rest/*##: REST resources, served by the XWiki REST Servlet
33 * ##/xmlrpc/*##: XML-RPC resources, served by the XWiki XMLRPC Servlet
Guillaume Fenollar 43.1 34 * ##/resources/~*~*/*.gwtrpc##: GWT-RPC calls, served by the XWiki GWT Servlet
Vincent Massol 35.1 35 * ##/webdav/*##: WebDav calls, served by the XWiki WebDAV Servlet
36 * ##/XWikiService##: Another XWiki GWT Servlet
Vincent Massol 29.1 37 * ##/redirect##: The XWiki Redirect Servlet used to redirect to the home page when no page is specified in the URL
maalej 1.1 38
Vincent Massol 38.1 39 There are various alternate to achieve this:
Dmitry Bakbardin 20.1 40
Vincent Massol 38.1 41 {{toc scope="local"/}}
42
Vincent Massol 37.1 43 {{info}}
44 You might be tempted to configure just your XWiki's ##web.xml## file [[but this won't work>>ShortURLsInvalid]].
45 {{/info}}
46
Vincent Massol 29.1 47 == UrlRewriteFilter ==
48
Guillaume Fenollar 43.1 49 {{info}}
50 This is the simplest solution of all but you'll need XWiki 5.2+ because of [[this issue that was fixed in XWiki 5.2>>http://jira.xwiki.org/browse/XWIKI-9430]].
51 {{/info}}
Vincent Massol 29.1 52
Vincent Massol 36.1 53 "UrlRewriteFilter" is a [[framework offering a Servlet Filter>>http://www.tuckey.org/urlrewrite/]] allowing to rewrite URLs.
54
55 Install steps:
Guillaume Fenollar 43.1 56
Vincent Massol 36.1 57 1. [[Download the JAR>>http://www.tuckey.org/urlrewrite/]] and put it in ##WEB-INF/lib##
58 1. Edit your ##WEB-INF/web.xml## and add the ##<filter>## and ##filter-mapping## definitions [[as documented>>http://www.tuckey.org/urlrewrite/]]
59 1. Drop the following content in a file at ##WEB-INF/urlrewrite.xml##:(((
Jerome 14.1 60 {{code language="xml"}}
Vincent Massol 29.1 61 <?xml version="1.0" encoding="utf-8"?>
62 <!DOCTYPE urlrewrite PUBLIC "-//tuckey.org//DTD UrlRewrite 4.0//EN"
63 "http://www.tuckey.org/res/dtds/urlrewrite4.0.dtd">
Vincent Massol 42.1 64 <urlrewrite decode-using="null">
Vincent Massol 29.1 65
66 <rule>
67 <note>
68 Ensure that URLs ending with .gwtrpc are not modified.
69 </note>
70 <from>^/(.*)\.gwtrpc$</from>
71 <to type="forward" last="true">-</to>
72 </rule>
73
74 <rule>
75 <note>
76 En sure that URLs that must not be served by the Struts Servlet are not modified.
77 </note>
Dmitry Bakbardin 44.1 78 <from>^/(bin|resources|skins|rest|webdav|xmlrpc|wiki)/(.*)$</from>
Vincent Massol 29.1 79 <to type="forward" last="true">-</to>
80 </rule>
81
82 <rule>
83 <note>
84 For all other URLs we prepend the "/bin/" prefix so that they get routed to the XWiki Action Servlet.
85 </note>
86 <from>^/(.*)$</from>
87 <to type="forward">/bin/$1</to>
88 </rule>
89
Vincent Massol 32.1 90 <outbound-rule>
91 <note>
92 Rewrite outbound URLs to remove the "/bin" part.
93 </note>
94 <from>/bin/(.*)/(.*)$</from>
95 <to>/$1/$2</to>
96 </outbound-rule>
97
Vincent Massol 29.1 98 </urlrewrite>
99 {{/code}}
Vincent Massol 36.1 100 )))
Vincent Massol 29.1 101
Vincent Massol 39.1 102 == Apache ==
Jerome 16.1 103
Vincent Massol 39.1 104 Strategy:
Guillaume Fenollar 43.1 105
106 * Tell Apache that ##/skins## and ##/resources## URLs (except for ##/resources/~*~*/*.gwtrpc## ones) are served statically so that they don't go through the Servlet container
107 * Configure ##web.xml## so that ##/*## URLs go through the Struts Servlet and so that ##/resources/~*~*/*.gwtrpc## URLs go through the GWT Servlet
Vincent Massol 39.1 108 * Tell XWiki to not generate URLs with ##bin## in the path
Sergiu Dumitriu 4.1 109
Vincent Massol 39.1 110 Configuration steps:
Guillaume Fenollar 43.1 111
Vincent Massol 39.1 112 * Setup the following Apache configuration:(((
113 {{code language="apache"}}
Manuel Smeria 19.4 114 Alias /skins /usr/local/xwiki/skins
115 Alias /resources /usr/local/xwiki/resources
Jerome 19.1 116
Vincent Massol 34.1 117 RewriteEngine on
118
119 RewriteRule ^/+skins - [L]
120 RewriteCond %{REQUEST_URI} !\.gwtrpc$
121 RewriteRule ^/+resources($|/.*) - [L]
122
123 RewriteRule .* http://localhost:8080%{REQUEST_URI} [P,L]
124 ProxyPassReverse / http://localhost:8080/
125 {{/code}}
Vincent Massol 39.1 126 )))
Vincent Massol 41.1 127 * Edit ##web.xml## and add:(((
Vincent Massol 39.1 128 {{code language="xml"}}
129 <servlet-mapping>
130 <servlet-name>action</servlet-name>
131 <url-pattern>/*</url-pattern>
132 </servlet-mapping>
133 {{/code}}
134 )))
Vincent Massol 41.2 135 * Edit ##web.xml## and replace the existing mapping:(((
Vincent Massol 39.1 136 {{code language="xml"}}
137 <servlet-mapping>
138 <servlet-name>gwtrpc</servlet-name>
139 <url-pattern>*.gwtrpc</url-pattern>
140 </servlet-mapping>
141 {{/code}}
Vincent Massol 34.1 142
Vincent Massol 41.2 143 by
Vincent Massol 34.1 144
Vincent Massol 39.1 145 {{code language="xml"}}
146 <servlet-mapping>
147 <servlet-name>gwtrpc</servlet-name>
148 <url-pattern>/resources/*</url-pattern>
149 </servlet-mapping>
150 {{/code}}
151 )))
152 * Add the following in ##xwiki.cfg## (empty value after the equal sign):(((
Jerome 14.1 153 {{code language="none"}}
Vincent Massol 39.1 154 xwiki.defaultservletpath=
Jerome 14.1 155 {{/code}}
Guillaume Fenollar 43.1 156 )))
Vincent Massol 39.1 157 * {{info}}Only for XWiki 5.2+{{/info}} Add the following in ##xwiki.properties## (empty value after the equal sign):(((
158 {{code language="none"}}
Guillaume Fenollar 43.1 159 url.standard.getEntityPathPrefix=
Vincent Massol 39.1 160 {{/code}}
161 )))
PaulHarris 12.1 162
Vincent Massol 39.1 163 {{warning}}
164 There's a regression in XWiki 5.1 that will prevent this to work correctly. To overcome it, we recommend that you upgrade to XWiki 5.2. If you cannot, you could do the following:
165 * Remove the 3 ##xwiki-platform-url-*## JARs you have in your ##WEB-INF/lib## directory and instead add the following:
166 ** http://maven.xwiki.org/releases/org/xwiki/platform/xwiki-platform-url-api/5.2-milestone-2/xwiki-platform-url-api-5.2-milestone-2.jar
167 ** http://maven.xwiki.org/releases/org/xwiki/platform/xwiki-platform-url-container/5.2-milestone-2/xwiki-platform-url-container-5.2-milestone-2.jar
168 ** http://maven.xwiki.org/releases/org/xwiki/platform/xwiki-platform-url-standard/5.2-milestone-2/xwiki-platform-url-standard-5.2-milestone-2.jar
169 * Edit your ##xwiki.properties## file and add (no value after the equal sign):(((
Dmitry Bakbardin 23.1 170 {{code}}
Vincent Massol 39.1 171 url.standard.entityPathPrefix=
Dmitry Bakbardin 23.1 172 {{/code}}
Vincent Massol 39.1 173 )))
174 {{/warning}}
Dmitry Bakbardin 23.1 175
Vincent Massol 39.1 176 == Others ==
Dmitry Bakbardin 24.1 177
Vincent Massol 39.1 178 Some XWiki users have contributed other solutions but they've not been verified by a XWiki Development Team member at this stage so use at your own risk ;)
Dmitry Bakbardin 24.1 179
Vincent Massol 39.1 180 * [[Lighttpd + Jetty>>ShortURLsLighttpdJetty]]
PaulHarris 12.1 181
Dmitry Bakbardin 20.1 182 = III. Struts action name =
Jerome 14.1 183
Manuel Smeria 19.4 184 The third part, ##/view/##, identifies the struts action that should process a request. So this tells what we want to do with the document, ##/view/## it, ##/edit/## it or ##/delete/## it, for example. The XWiki platform allows this part to be missing, considering that the default action is to just display the document, so an URL like ##server.com/bin/Space/Document## will work out of the box.
185
186 Even more, the URL factory, the component that generates URLs, can be configured to skip this part when the action is ##/view/##. To do this write this code in ##xwiki.cfg##: {{code language="none"}}xwiki.showviewaction=0{{/code}}.
187
Dmitry Bakbardin 20.1 188 = IV. Error Page =
Manuel Smeria 19.4 189
Jerome 14.1 190 At the ##WEB-INF/web.xml##, the ##location## of the 404 error code needs to be changed accordingly. For example:
191
192 {{code language="xml"}}
193 <error-page>
mingfai 9.1 194 <error-code>404</error-code>
195 <!--<location>/xwiki/bin/view/Main/DocumentDoesNotExist</location>-->
196 <location>/bin/Main/DocumentDoesNotExist</location>
197 </error-page>
Jerome 14.1 198 {{/code}}
mingfai 9.1 199
Dmitry Bakbardin 20.1 200 = V. Conclusion =
Sergiu Dumitriu 4.1 201
202 After performing all these changes, you should be able to access documents with URLs like:
Jerome 14.1 203
Sergiu Dumitriu 4.1 204 * server.com/Space/Document
205 * server.com/Space/ (pointing to Space.WebHome)
206 * server.com/Document (pointing to Main.Document)
207 * server.com/ will show Main.WebHome, without any redirect.
208
Vincent Massol 5.1 209 As a bonus, these changes are backwards compatible, meaning that any currently working URL will also work with these changes performed, so you won't have any broken bookmarks.

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected