Wiki source code of ShortURLs
Version 10.2 by Vincent Massol on 2008/11/12
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | #startfloatingbox() | ||
| 2 | *Content* | ||
| 3 | #toc("" "" "") | ||
| 4 | #endfloatingbox() | ||
| 5 | |||
| 6 | 1 Short XWiki URLs | ||
| 7 | |||
| 8 | This tutorial shows how to tune your XWiki platform by replacing the default URL scheme with a shorter scheme. | ||
| 9 | |||
| 10 | #info("A short URL is an URL without the <tt>xwiki/bin/view</tt> parts.") | ||
| 11 | |||
| 12 | 1.1 Application name | ||
| 13 | |||
| 14 | The <tt>/xwiki/</tt> 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 <tt>webapps</tt> directory, in a sub directory named after the application name you wish to use (e.g. <tt>webapps/myappname</tt>). | ||
| 15 | |||
| 16 | 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 <tt>server.com/bin/view/Space/Document</tt>. Achieving this again depends on the container, as there's no standard regarding the ROOT application. For example in Tomcat, with the default configuration, all it takes is to deploy the XWiki web application in <tt>webapps</tt>, in a sub directory named <tt>ROOT</tt> (i.e. <tt>webapps/ROOT</tt>). In Jetty, the default name is <tt>root</tt>. Refer to your container's documentation for more details. | ||
| 17 | |||
| 18 | #warning("Before XWiki Platform 1.3, the the <tt>display-name</tt> parameter in <tt>web.xml</tt> must also be changed to reflect the new application name. For example if you've deployed the XWiki webapp as ROOT then you'll need to have: | ||
| 19 | {code:xml}<display-name></display-name>{code} | ||
| 20 | ") | ||
| 21 | |||
| 22 | 1.1 Struts action name | ||
| 23 | |||
| 24 | The third part, /view/, identifies the struts action that should process a request. So this tells what do 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 <tt>server.com/bin/Space/Document</tt> will work out of the box. | ||
| 25 | |||
| 26 | 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, in <tt>xwiki.cfg</tt> write: | ||
| 27 | |||
| 28 | {code:none}xwiki.showviewaction=0{code} | ||
| 29 | |||
| 30 | 1.1 Servlet mapping name | ||
| 31 | |||
| 32 | 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. To get rid of /bin/, for the moment <tt>web.xml</tt> must be changed in a | ||
| 33 | container-dependent way, so that the container's default servlet is configured to serve the existing directories, like skins, yui, tinymce and wikieditor. In Jetty, the container shipped with the XWiki installer, you will have to write something like: | ||
| 34 | |||
| 35 | {code:xml} | ||
| 36 | <servlet> | ||
| 37 | <servlet-name>defaultSkins</servlet-name> | ||
| 38 | <servlet-class>org.mortbay.jetty.servlet.Default</servlet-class> | ||
| 39 | <init-param> | ||
| 40 | <param-name>relativeResourceBase</param-name> | ||
| 41 | <param-value>skins</param-value> | ||
| 42 | </init-param> | ||
| 43 | <load-on-startup>1</load-on-startup> | ||
| 44 | </servlet> | ||
| 45 | <servlet-mapping> | ||
| 46 | <servlet-name>defaultSkins</servlet-name> | ||
| 47 | <url-pattern>/skins/*</url-pattern> | ||
| 48 | </servlet-mapping> | ||
| 49 | {code} | ||
| 50 | |||
| 51 | In Tomcat, the default servlet does not accept a parameter for changing the resource base, so you will need to write another default servlet. | ||
| 52 | |||
| 53 | The second thing to do, is to copy the mapping for the Struts servlet to also be activated for /, like: | ||
| 54 | {code:xml} | ||
| 55 | <servlet-mapping> | ||
| 56 | <servlet-name>action</servlet-name> | ||
| 57 | <url-pattern>/*</url-pattern> | ||
| 58 | </servlet-mapping> | ||
| 59 | {code} | ||
| 60 | Be sure to leave the other mappings in place, so that /bin/ works, too. | ||
| 61 | |||
| 62 | And the last thing that must be changed is the default mapping used by the URL factory, by adding in <tt>xwiki.cfg</tt>: | ||
| 63 | {code:none}xwiki.defaultactionpath={code} | ||
| 64 | |||
| 65 | 1.1 Error Page | ||
| 66 | At the <tt>WEB-INF/web.xml</tt>, the <tt>location</tt> of the 404 error code needs to be changed accordingly. For example: | ||
| 67 | {code:xml} | ||
| 68 | <error-page> | ||
| 69 | <error-code>404</error-code> | ||
| 70 | <!--<location>/xwiki/bin/view/Main/DocumentDoesNotExist</location>--> | ||
| 71 | <location>/bin/Main/DocumentDoesNotExist</location> | ||
| 72 | </error-page> | ||
| 73 | {code} | ||
| 74 | |||
| 75 | 1.1 Conclusion | ||
| 76 | |||
| 77 | After performing all these changes, you should be able to access documents with URLs like: | ||
| 78 | * server.com/Space/Document | ||
| 79 | * server.com/Space/ (pointing to Space.WebHome) | ||
| 80 | * server.com/Document (pointing to Main.Document) | ||
| 81 | * server.com/ will show Main.WebHome, without any redirect. | ||
| 82 | |||
| 83 | 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. |
