Orbeon Forms User Guide

URL Rewriting

1. Rationale

As a Web applications developer, you often have to write URLs in your Web pages. For example, an HTML <a> element contains an href attribute specifying the destination of a link. The URLs you write usually end up directly unmodified in the Web browser. This causes a number of problems, detailed below.

1.1. Problems with Servlets

Absolute URLs (starting with a scheme such as http: or https:) are usually reserved to refer to external sites or applications. But when referring to the current application, relative URLs, in the form of relative paths or absolute paths, are commonly used instead. In these cases, you must make sure that the URL interpreted by the Web browser and the application server refers to the correct page or resource:

  • Relative paths: such paths are interpreted by the Web browser as relative to a URL base, usually the URL of the page being requested, unless specified differently. For example, if a browser requests /ops/example1/page1:

    Relative Path Resulting Absolute Path
    page2 /ops/example1/page2
    ../page3 /ops/page3
    ../example2/page4 /ops/example2/page4

    The problem: if a page is moved, all the relative paths within that page have to be changed.

  • Absolute paths: such paths start with a "/". The issue with this solution is that you have to write the exact absolute path, including a servlet context path such as /ops.

    The problem: hardcoding the servlet context path in every URL makes it impossible to change the servlet context without changing all the URLs in the application. To alleviate this issue, you might use relative URLs, with the other problems mentioned above.

1.2. Problems with Portlets

The issue is even more important with Java Portlets (JSR-168), as URLs must be generated by calling a specific Java API. With page template languages such as JSP, this is done using tag libraries. All the pages in an application must be modified when moved from a deployment as a Servlet to a deployment as a Portlet.

1.3. Solution

With Orbeon Forms, the solution to these issues is called URL rewriting. It consists in transparently post-processing the URLs you write to make your life easier. This is possible thanks to the Orbeon Forms Page Flow Controller epilogue, which contains a URL rewriting mechanism for HTML and XHTML documents.

2. URL Rewriting Strategy

This section describes the default URL rewriting implementation in Orbeon Forms. It is implemented in the processors oxf:xhtml-rewrite and oxf:html-rewrite.

2.1. What is Rewritten?

The form, a, link, img, input and script elements are rewritten in HTML documents. Their XHTML counterparts in the http://www.w3.org/1999/xhtml namespace are rewritten in XHTML documents. Note that:

  • Absolute URLs (i.e. with a scheme) are left unmodified.

  • The special case of URLs starting with a query string (e.g. ?name=value) is handled. This last syntax is supported by most Web browsers and because of its convenience, it is supported by the default rewriting algorithm as well.

Note
URLs are parsed by the rewriting algorithm, so you must make sure that URLs are well-formed.
Note
Rewriting also occurs on some XForms elements. In that case, rewriting is handled by the XForms engine. For details, refer to URLs in XForms in the XForms documentation.

2.2. Servlets

Element / Attribute Action
form/@action

URLs are rewritten as follows:

  • If the URL is a relative path, it is left unchanged.
  • If the URL is an absolute path, the servlet context path is pre-pended.
  • Absolute URLs are left unchanged.
a/@href
link/@href
img/@src
input[@type='image']/@src
script/@src

2.3. Portlets

With Portlets, you write your URLs as you would in a regular Servlet-based application, and the rewriting processors take care of calling the Portlet API to encode the URLs. As you may know, portlets make a distinction between several URL types:

  • Render URLs

  • Action URLs

  • Resource URLs

Orbeon Forms rewrites URLs to these different types based on the HTML or XHTML attribute names as follows:

Element / Attribute Action
form/@action Rewritten to an action URL using the Portlet API method RenderResponse.createActionURL(). The resulting URL results in an action URL targeting the current portlet. Absolute URLs are left unchanged.
form/@method If no form/@method is supplied, an HTTP POST is forced, because the Portlet specification recommends submitting forms with POST. If a method is supplied, the method is left unchanged.
a/@href Rewritten to a render URL using the Portlet API method RenderResponse.createRenderURL(). The resulting URL results in a render URL targeting the current portlet. Absolute URLs are left unchanged.
img/@src Rewritten to a resource URL encoding. The resulting URL points to a resource within your Web application. Absolute URLs are left unchanged.
input[@type='image']/@src
script/@src
link/@href
script and SCRIPT In text within those elements or their XHTML counterparts in the http://www.w3.org/1999/xhtml namespace, occurrences of the string wsrp_rewrite_ are replaced with the Portlet namespace as obtained by the Portlet API method RenderResponse.encodeNamespace(null).

Note that since portlets do not have the concept of path, URL paths are encoded as a special portlet parameter named oxf.path. Relative paths are resolved against the current path stored in oxf.path. The following table illustrates action URL and render URL rewriting:

Initial Path Resulting Portlet Parameters
/example1/page1?name1=value1&name2=value2
  • oxf.path=/example1/page1
  • name1=value1
  • name2=value2
?name1=value1&name2=value2
  • name1=value1
  • name2=value2
Assuming the current value of oxf.path is /example1/page1:

../example2/page2?name1=value1&name2=value2
  • oxf.path=/example2/page2
  • name1=value1
  • name2=value2

The following table illustrates resource URL rewriting:

Initial Path Resulting Path
/path/to/my/image.gif?scale=100 /ops/path/to/my/image.gif?scale=100
Assuming the current value of oxf.path is /example1/page1:

my/image.gif?scale=100 		/ops/example1/my/image.gif?scale=100

Note that using resource URLs relative to oxf.path does not necessarily make sense unless you define your hierarchy of resources carefully.

3. Working with URL Rewriting

3.1. Suggested URL Formats

With Orbeon Forms, it is recommended you write URLs as:

  • Absolute URLs, when referring to external resources:

    <a href="http://www.google.com/">Go to Google</a>

  • Relative paths, for resources that are likely to remain fixed relatively to the page containing the URL:

    <img src="../images/back.png"/><a href="edit-page">Go to the Edit Page</a>

  • Absolute paths (without the servlet context path) in all other cases:

    <img src="/images/back.png"/><a href="/apps/my-app/edit-page">Go to the Edit Page</a>

3.2. Controlling URL Rewriting

In certain cases, you may want to disable URL rewriting. This is done through an extension attribute:

<a href="/my/path" f:url-norewrite="true">Follow Me</a>

With portlets, you may want to control the type of URL instead of using the default URL type. You control this with an extension attribute:

<a href="/my/path" f:url-type="action">Follow Me</a>

Without f:url-type="action", the URL would be handled by Orbeon Forms as a "render" URL as described in the table of the previous section.

For both attributes, you have to make sure that the namespace xmlns:f="http://orbeon.org/oxf/xml/formatting" is declared. You can declare it once and for all on the root element of your document.

4. Known Limitations

4.1. Portlets

  • The input document should not contain:

    • Elements and attribute containing the string wsrp_rewrite
    • Namespace URIs containing the string wsrp_rewrite
    • Processing instructions containing the string wsrp_rewrite

  • It is not possible to specify:

    • A destination portlet mode
    • A destination window state
    • A secure URL